spoon

spoon helps you explore open source repos and dependencies with agents.

It removes friction from finding a repo, cloning or opening it, and launching your preferred agent CLI in the project immediately.

Why use it

• Fast interactive repo selection from local clones.
• Search GitHub and pick a repo with fuzzy selection.
• Open exact repos directly with org/repo or full URL.
• Launch with configurable aliases (claude, codex, custom commands).
• Keep your local cache clean with TTL-based purge.

Install

Requirements:

• bun
• fzf
• GitHub CLI (gh)
• Agent CLI commands you want to launch (claude, codex, wrappers, etc.)

bun install
bun link

Command Reference

Command	Description
spoon	Open a local repo interactively.
spoon <org/repo>	Open by exact match.
spoon <url>	Open by full GitHub URL.
spoon <search>	Search GitHub and select interactively.
spoon <org/repo> [-l <alias>] [-b <branch>]	Open with launch alias and/or branch override.
spoon <org/repo> [-- <command...>]	Override launch command for one run.
spoon ls	List local repos and history entries.
spoon add <repo> [-b <branch>]	Resolve or clone a repo without launching.
spoon context	Interactively select history repos to link into .spoon/.
spoon context <repo> [--name <name>]	Link repo context into the current project's .spoon/.
spoon context ls	List context links in the current project.
spoon context remove [<repo-or-name>]	Remove context links by ref or interactive picker.
spoon remove	Interactively select local repos to remove.
spoon config	Open config file in your system default app.
spoon help [command]	Show help.
spoon <command> --help	Show command-specific help.

Open repos

Open local repo interactively

Description: Open a local repo from an interactive picker.

Syntax:

spoon

Example:

spoon

Open by exact repo or URL

Description: Open or clone directly using exact org/repo or full URL.

Syntax:

spoon <org/repo>
spoon <url>

Examples:

spoon sveltejs/kit
spoon https://github.com/sveltejs/svelte

Search and select from GitHub

Description: Search GitHub repos, then pick one interactively.

Syntax:

spoon <search>

Example:

spoon svelte

Use launch, branch, and command overrides

Description: Control how the selected repo is launched.

Syntax:

spoon <org/repo> -l <alias>
spoon <org/repo> -b <branch>
spoon <org/repo> -- <command...>

Examples:

spoon sveltejs/kit -l x
spoon sveltejs/kit -b next
spoon sveltejs/kit -- claude --continue

Manage local repos

Add repo without launching

Description: Resolve or clone a repo using the same lookup flow as spoon <query>, but do not launch an agent process.

Syntax:

spoon add <org/repo>
spoon add <url>
spoon add <search>
spoon add <org/repo> -b <branch>

Examples:

spoon add sveltejs/kit
spoon add https://github.com/sveltejs/svelte
spoon add svelte
spoon add sveltejs/kit -b next

Manage project context links

Link repo context into this project

Description: Create a symlink in the current working directory under .spoon/ that points to a locally cached repo. Default links use .spoon/<org>_<repo>; --name uses .spoon/<name>.

Syntax:

spoon context
spoon context <org/repo>
spoon context <repo> --name <name>

Examples:

spoon context
spoon context sveltejs/kit
spoon context sveltejs/kit --name kit

List context links

Description: Show context links currently present in this project's .spoon/ directory.

Syntax:

spoon context ls

Example:

spoon context ls

Remove context links

Description: Remove one or more context links from this project's .spoon/ directory.

Syntax:

spoon context remove
spoon context remove <repo-or-name>

Examples:

spoon context remove
spoon context remove sveltejs/kit
spoon context remove kit

List repos

Description: Print locally available repos and historical repos no longer present.

Syntax:

spoon ls

Example:

spoon ls

Remove repos

Description: Interactively select one or more local repos to remove.

Syntax:

spoon remove

Example:

spoon remove

Open config

Description: Open spoon config file in your default system app.

Syntax:

spoon config

Example:

spoon config

Help

Show help

Description: Show global help or command-specific help.

Syntax:

spoon help [command]
spoon <command> --help

Example:

spoon ls --help

Configuration

Config path:

~/.config/spoon/config.json

Example config:

{
  "launch": {
    "c": "claude",
    "x": {
      "name": "Codex",
      "command": "codex"
    },
    "t": {
      "name": "AI Tmux",
      "command": "tmux new -A -s ai && claude"
    }
  },
  "ttlMs": 1209600000,
  "baseDir": "~/ai-scratch/gh"
}

Notes:

• Default launch alias is the first key in launch.
• Launch entries support both alias: command and alias: { "name": "...", "command": "..." }.
• For alias: command, the launch name is inferred from the command (for example, "x": "codex" shows Codex).
• Repos are purged by TTL on invocation after local repo count grows (10+ repos).

License

MIT