code/commands/builtins/github.md

---
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:

```bash
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.