octocode

Octocode CLI — Agent Playbook

Binary: octocode. Run octocode --help to see everything; it prints an <AGENT_INSTRUCTIONS> block plus the full command list. Two surfaces:

1. Quick commands — friendly shortcuts that auto-route a local path vs an owner/repo. Use these first.
2. Raw tools — octocode tools <name> --queries '<json>' runs an Octocode MCP tool directly. Read the schema FIRST.

Discipline (read this first)

• Do NOT hallucinate paths, line numbers, or fields — verify with the tools. Search snippets are discovery, not proof; re-read the exact text before quoting.
• Flow: locate → search → read the smallest slice → prove. Pick the cheapest tool that answers the current question.
• One wide query beats five narrow ones. If results are reasonable, read them — don't re-query to "narrow down".
• Parallelize independent calls — issue them in one message so the shell runs them concurrently.
• Output: clean YAML by default (read it directly). Add --json for the raw envelope, --compact for the leanest text.

Task → quick command

What you need	Command
Directory / repo layout	octocode ls <path|owner/repo> [--depth 2]
Read (and minify) a file	octocode cat <path|owner/repo/path> [--mode none|standard|symbols] [--match-string '<anchor>']
Text / regex code search	octocode grep '<keywords>' <path|owner/repo> [--type ts]
Find files by name/path/content	octocode find '<query>' [path|owner/repo] [--search path|content|both]
Code-shape search (AST, local)	octocode ast '<pattern>' [path]
Symbol outline of a file/dir	octocode symbols <file|dir>
Symbol identity (defs/refs/callers)	octocode lsp <file> --type references --symbol <name> --line <n>
Discover GitHub repositories	octocode repo '<keywords>' [--language ts --stars '>100']
Pull requests (list or deep-read)	octocode pr <owner/repo[#N]|PR-URL> [--deep]
npm package + source repo	octocode pkg <package>
Inspect an archive / binary	octocode binary <file>
Unpack an archive for multi-file work	octocode unzip <archive>
Clone a repo/subtree for deep work	octocode clone <owner/repo[/path][@branch]>

Quick commands route by their argument: a path that exists locally (or starts with ./, /, ../) is local; owner/repo[/path], owner/repo@branch, or a github.com URL is GitHub. Per-command details: octocode <command> --help.

Raw tools (when a quick command doesn't fit)

octocode tools                       # list every tool with its required fields
octocode tools <name> --scheme       # READ THE SCHEMA FIRST — fields, types, bounds, defaults
octocode tools <n1> <n2> --scheme    # read several schemas at once
octocode tools <name> --queries '<json>'          # run it (one object, or an array of ≤5)
octocode tools <name> --queries '<json>' --json   # raw envelope

Never guess fields — read the schema. id, mainResearchGoal, researchGoal, reasoning are auto-filled; don't pass them. Batch up to 5 independent sub-queries in one call:

octocode tools ghSearchCode --queries '[
  {"keywordsToSearch":["useState"],"owner":"facebook","repo":"react"},
  {"keywordsToSearch":["useEffect"],"owner":"facebook","repo":"react"}
]' --json | jq

Recipes

Symbol lookup (definition + callers):

octocode grep 'runCLI' bgauryy/octocode-mcp --type ts --limit 10
octocode cat bgauryy/octocode-mcp/packages/octocode/src/cli/index.ts --match-string 'export function runCLI' --mode none

Workspace mapping (layout + each package.json): one ls --depth 2, then parallel cat calls for each package.json in a single message.

Deep multi-file work in one repo (>~3 files): octocode clone owner/repo, then run grep/ast/symbols/lsp/cat on the local clone instead of many GitHub round-trips.

On failure

A bad flag prints the valid flags for that command and exits 2. Exit codes: 0=ok, 2=bad-input, 3=not-found, 4=auth, 5=tool-error, 7=rate-limited.

Auth

Auth is for humans: octocode login (or gh auth login). Agents/CI pass a token via env — GITHUB_TOKEN, OCTOCODE_TOKEN, or GH_TOKEN. Check with octocode status.

Deeper context

octocode context (add --full) prints the agent protocol, MCP system prompt, and tool descriptions — use it only to optimize deeper or autonomous research. Full docs: https://github.com/bgauryy/octocode/tree/main/docs