Octocode Code Research

What it does

When your agent uses it

• Tracing what calls a function and what breaks if you change it
• Finding the root cause of a failure with evidence from the code
• Researching an external repository or npm package before depending on it
• Planning a change before writing code and validating it afterwards

Example prompts

• “Research this: where is the retry logic for failed webhooks and who calls it?”
• “Use octocode to find out what breaks if I rename the parseConfig function.”
• “Find the root cause of the intermittent timeout in the upload service, with file and line evidence.”
• “Look into how the upstream library handles token refresh and compare it to our wrapper.”

Requirements

• The Octocode toolset, used through MCP or its CLI

Workflow steps

7 steps, taken from the first numbered list in SKILL.md.

1. 1Open with one line: corpus, actual vs desired, task class, mode, surfaces used and skipped.
2. 2Call it a bug only when evidence shows a supported contract was violated.
3. 3Root cause needs mechanism, trigger, violated contract, divergence boundary, and a killed alternate.
4. 4Use the strongest handle you already hold. For nontrivial claims check two of: structure, stream, connections.
5. 5A snippet is a lead. Empty means this lane can't see it, not it isn't there. Say which you mean.
6. 6Track claim → evidence → confidence → next check. Cite exact anchors, and only checks that actually ran.
7. 7Ask before broad contracts, deletes/renames, thin evidence, or a third unrelated search space. Patch after proof.

What it can do on your machine

Read from SKILL.md and the folder at commit c265e3f. It shows what the files ask for, not the result of running them.

• Tool permissions

  Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

  From allowed-tools in the SKILL.md frontmatter.

• Runs code

  Ships 1 file in scripts/, which the agent can run.

  Shell commands in SKILL.md call:

  • npx
  • node

  From the folder's file list and the shell code blocks in SKILL.md.

• Network

  No URLs in SKILL.md. Its commands use npx, which can reach the network depending on how they are called.

  From URLs in SKILL.md, links to its own repository left out.

• Credentials

  Names no API keys, tokens, secrets or passwords.

  From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Octocode Code Research loads about 1.5k tokens when it runs, and up to ~15k if it reads all its reference files. Until then it costs about 167 tokens; SKILL.md has 603 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it

~167

When it runs · the whole SKILL.md, loaded when a task matches

~1.5k

With references · SKILL.md plus every file in references/, read only if the agent opens them

~15k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); the scripts in this folder are not scanned.

SKILL.md

The full file from bgauryy/octocode at commit c265e3f, republished under its MIT licence (© bgauryy). 603 words, ~1,473 tokens.

name

octocode-research

description

Use when code must be checked, not assumed: trace connections (callers, imports, cross-repo wiring, what breaks if I change it), locate behavior, map a system, diagnose a failure, RCA. Also for external repositories, npm packages, upstream/prior art, and general research. Plan a coding flow before writing, validate it after. Triggers on 'research this' or 'use octocode'. Gives exact file:line/PR/commit evidence with confidence. Skip trivial edits whose blast radius is already known. Not for authoring or copyediting the docs themselves, or for building skill folders: docs deliverable → octocode-documentation; SKILL.md folders → octocode-skills.

FRAME → CLASSIFY → MODEL → SEARCH → READ EXACT → PROVE → DECIDE/PATCH → VERIFY

npx octocode context --minimal                         # what's available
npx octocode tools <name> --scheme --json --compact    # read fields — never guess
npx octocode tools <name> --queries '<json>' --compact # run it

© bgauryy, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 24 other files (scripts, references) in skills/octocode-research of bgauryy/octocode.

• SKILL.md
• README.md
• agents/openai.yaml
• references/algorithm.md
• references/code-research.md
• references/github-landscape.md
• references/improve-loop.md
• references/long-research.md
• references/loop-mode.md
• references/octocode.md
• references/problem-framing.md
• references/research-flow.md
• references/researcher-mindset.md
• references/workflow-change.md
• references/workflow-combination.md
• references/workflow-debug.md
• references/workflow-external.md
• references/workflow-local.md
• references/workflow-pr-review-analysis.md
• … and 6 more

Open the folder on GitHubat commit c265e3f