code/commands/builtins/github.md

metadata

name: github
description: Import a GitHub repository into the workspace so the agent can edit it
argument-hint: <github-url> [subdir] [--branch <name>] [--into <path>]
allowed-tools: >-
  read_file, write_file, edit_file, multi_edit, list_dir, glob, grep, bash,
  todo_read, todo_write, todo_update

GitHub Import Command

The user invoked /github with arguments: $ARGUMENTS

Parse the arguments

The argument string after /github is $ARGUMENTS. Parse it as:

• A required GitHub URL (first token starting with https://github.com/ or git@github.com:).
• An optional subdir — the second positional token if it doesn't start with --.
• Optional flags:
  • --branch <name> — checkout this branch/tag instead of the URL's default.
  • --into <path> — place the import under <path>/ inside the workspace instead of the root.
  • --depth <N> — git clone depth (default 1).
  • --timeout <s> — clone timeout in seconds (default 120).

Execute the import

Use the bash tool to call the Python helper directly:

python -c "from code.tools.github import import_github_repo; import json; print(json.dumps(import_github_repo(url='<URL>', branch='<BRANCH>', subdir='<SUBDIR>', target_subdir='<INTO>', depth=<DEPTH>, timeout=<TIMEOUT>), default=str))"

(Quote arguments correctly; if any are empty, pass the empty string.)

If the bash tool is unavailable, use write_file to drop a small script and then run it with bash.

After the import

1. Read the JSON output of the command above.
2. If success is true:
   • Use list_dir on the workspace root (or the --into path) to confirm what landed.
   • Read the top-level files you expect to find: README.md, package.json, requirements.txt, pyproject.toml, app.py, index.html — whichever exist.
   • Summarize for the user:
     • Repo imported: owner/repo (branch: X)
     • Files imported: N
     • Heavy dirs stripped: M
     • Workspace location: path/
     • A 5-10 line preview of what's in the workspace now.
   • Suggest next steps based on the project type (e.g. "Want me to add tests? Modernize the build? Add a Dockerfile?").
3. If success is false:
   • Surface the message to the user verbatim.
   • If the error mentions subdir_not_found, list the top-level directories of the repo (you can re-run the import with --depth 1 and no subdir to discover what's there, or use git ls-tree via bash).
   • If the error mentions git binary not found, tell the user git must be installed in the SoniCoder runtime.

Examples the user might type

• /github https://github.com/fastapi/fastapi
• /github https://github.com/vercel/next.js examples/with-typescript --into next-ts-demo
• /github https://github.com/pallets/flask --branch 2.3.x
• /github git@github.com:owner/repo.git

Rules

• NEVER push to or modify the upstream repo. The clone is local-only and stripped of .git.
• NEVER include secrets, API keys, or .env files in your summary — if you spot any, warn the user.
• If the workspace already has files, warn the user that the import will overwrite the destination directory before running.