# Witan Code

> >

- **Type:** Skill
- **Install:** `agentstack add skill-mitodl-agent-kit-witan-code`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [mitodl](https://agentstack.voostack.com/s/mitodl)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** BSD-3-Clause
- **Upstream author:** [mitodl](https://github.com/mitodl)
- **Source:** https://github.com/mitodl/agent-kit/tree/main/mcp/servers/witan-code/witan_code/skills/witan-code

## Install

```sh
agentstack add skill-mitodl-agent-kit-witan-code
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Code Graph

A per-repo, tree-sitter-derived graph of symbols (functions, methods, classes,
modules) and their relationships (`Calls`, `References`, `Imports`,
`Inherits`), plus a cross-repo bridge linking services through shared
contracts (env vars, HTTP endpoints, packages, deployments). Indexing is
automatic — a session-start hook seeds/refreshes the whole repo in the
background, and a post-edit hook incrementally reindexes each file you edit
(Claude Code's `SessionStart`/`PostToolUse` hooks; under Pi, the witan-code
extension's `session_start`/`tool_result` handlers) — so you rarely need to
invoke the CLI yourself.

## When to use this vs. grep / the `Explore` agent

Reach for `code_*` tools when the question is **structural**, not textual:

- "Where is `Service.run` defined?" → `code_find_definition` / `code_search_symbol`
- "What calls this function, anywhere in the repo?" → `code_callers` / `code_find_references`
- "If I change this, what breaks?" (transitive blast radius) → `code_impact`
- "What symbols does this file define?" → `code_symbols_in_file`
- "Which other repo reads this env var / calls this endpoint / imports this package?" → `code_interface_consumers` / `code_interface_providers` / `code_cross_repo_impact`

Grep is still the right tool for literal string/comment searches, one-off text
matches, or a repo with no code graph yet. The two are complementary: grep
finds text; `code_*` tools resolve **symbols** and their **relationships**,
which grep cannot do (it can't tell you a function's transitive callers or
which service consumes an endpoint another service serves).

**Caveat:** `Calls`/`References`/`Imports`/`Inherits` edges are heuristic
(syntactic name resolution, not a true call graph) — treat impact/caller
results as a high-recall starting point, not a verified answer. `Defines` and
`Contains` are exact.

## On invocation

- No args → **Check readiness**, then show the tool reference below.
- `reindex` → call the `code_reindex` MCP tool (or `witan-code reindex` if
  running the CLI directly) to force a full rebuild of the current repo,
  ignoring content hashes. Use when the graph looks stale and you don't want
  to wait for the incremental hooks to catch up.

## Check readiness

Before relying on results, confirm the current repo has a graph: call
`code_symbols_in_file` on a file you know exists, or `code_search_symbol` with
a term you expect to match. An empty result on a file/symbol you know exists
usually means indexing hasn't finished yet (the session-start index runs
detached in the background on a fresh repo) — wait a few seconds and retry
before concluding the graph is broken.

## Calling the tools

The tables below give each tool's bare name and arguments. How you reach one
depends on the agent:

- **Claude Code** — the `code_*` tools often arrive deferred (listed, no
  schema). Load them with
  `ToolSearch(query="+code_ find_definition callers impact")`, then call them
  directly: `code_find_definition(name="X")`. Their full names carry an
  `mcp____` prefix that depends on your MCP config, which is why the
  `+code_` query form is used rather than `select:`.
- **Pi** — Pi has no `ToolSearch`. pi-mcp-adapter puts every MCP tool behind
  its `mcp` proxy tool, under a server-prefixed name (for example
  `witan-code_code_find_definition`, or `witan_code_find_definition` when
  witan serves the code tools). Search for the exact name, then call it with
  `args`:
  `mcp({ search: "code_find_definition callers impact" })`, then
  `mcp({ tool: "", args: { name: "X" } })`.
  Search reads only cached tool metadata, so if it finds nothing, run
  `mcp({ connect: "witan-code" })` (or `"witan"`) and search again.
  `mcp({ describe: "" })` shows a tool's parameters. Invoke this skill
  as `/skill:witan-code`.

## Tool reference

| Question | Tool |
|---|---|
| Find a symbol by name | `code_find_definition(name)` / `code_search_symbol(query)` (BM25) |
| What's in this file? | `code_symbols_in_file(path)` |
| Who references/calls this symbol? | `code_find_references(symbol_id)` (References+Calls) / `code_callers(symbol_id)` (Calls only) |
| Blast radius of a change | `code_impact(symbol_id, max_depth=5, max_nodes=200)` — transitive callers via BFS |
| Force a reindex | `code_reindex(path=None)` |

Cross-repo (reads the shared bridge store; `kind` is one of `env_var` /
`endpoint` / `package` / `service`):

| Question | Tool |
|---|---|
| Who provides this contract? | `code_interface_providers(kind, key)` |
| Who consumes it? | `code_interface_consumers(kind, key)` |
| Every binding for this symbol's contracts, across repos | `code_cross_repo_impact(symbol_id)` |
| Search bindings by key | `code_interface_search(query, kind=None)` |
| What does this repo export / expect? | `code_repo_symbols(repo=None, role=None)` |
| Which repos depend on which? | `code_repo_dependencies(kind=None, repo=None)` |

Coverage — ask these before concluding "nothing uses X", since an unindexed
repo looks identical to an unused one:

| Question | Tool |
|---|---|
| Which repos are indexed, and how fresh? | `code_indexed_repos()` |
| Can the stores actually be read at all? | `code_store_health()` |
| Which branch views does a repo's store have? | `code_indexed_branches()` |

`code_store_health()` is the one to reach for when `code_interface_*` or
`code_cross_repo_impact` come back empty or erroring. Those four tools read one
shared *bridge* graph that belongs to no repo, so it shows up in no repo
listing — a bridge that cannot be opened breaks all of them while
`code_indexed_repos()` still lists every repo happily. In `code_indexed_repos`
output, `files: null` with a non-null `unreadable` means the same thing per
repo: that store errors, it is not merely sparse.

Every tool resolves the per-repo store from the current working directory and
returns `[]`/`null` gracefully when nothing is indexed yet — an empty result
is not necessarily an error, see **Check readiness** above.

## Linking to witan (tasks and memories)

`code_find_definition` / `code_search_symbol` return a `symbol_id` of the form
`#::`. Attach it to a witan task
(`task_create(..., symbol_refs=[...])`, see `/witan-task`) or memory
(`memory_store(..., symbol_refs=[...])`, see `/witan-memory`) so the work or
lesson is discoverable from the code later. Going the other way,
`symbol_context(symbol_id)` (a witan tool) lists the tasks and memories
already attached to a symbol — call it before editing code that might have
open work or known gotchas attached.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [mitodl](https://github.com/mitodl)
- **Source:** [mitodl/agent-kit](https://github.com/mitodl/agent-kit)
- **License:** BSD-3-Clause

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-mitodl-agent-kit-witan-code
- Seller: https://agentstack.voostack.com/s/mitodl
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.