> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trykode.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# kode plan — Build a Token-Capped Codebase Context Graph

> kode plan uses Tree-sitter AST analysis to build a surgical context graph of relevant files and symbols, capped at 8,000 tokens by default.

`kode plan` analyzes your codebase and produces a compact, task-focused context graph — only the files and symbols that are actually relevant to what you're trying to do. It uses Tree-sitter for AST-level parsing, so it understands your code structurally rather than relying on fuzzy string matching. The graph is token-capped (8,000 by default) to keep LLM costs predictable and context quality high.

## Synopsis

```bash theme={null}
kode plan <task>
```

## What it does

`kode plan` takes your task description, parses your codebase with Tree-sitter, builds a dependency graph of files and symbols, and trims it to fit within the token budget. The result shows you exactly which files and symbols Kode thinks are relevant, how they relate to each other, and what the LLM will see when you run `kode generate` or `kode loop`.

By default, `kode plan` prints a human-readable summary to the terminal. Use `--packet` to emit machine-readable JSON that you can pipe directly into `kode generate` or `kode loop` via `--context-file`.

## Flags

<ParamField path="--graph" type="boolean" default="false">
  Output the raw dependency graph as JSON instead of the human-readable summary. Useful for debugging context quality or piping into other tools.

  ```bash theme={null}
  kode plan --graph "fix the user service" | jq '.nodes | length'
  ```
</ParamField>

<ParamField path="--packet" type="boolean" default="false">
  Output the LLM-ready context packet as JSON. This is the compact representation that `kode generate` and `kode loop` consume via `--context-file`.

  ```bash theme={null}
  kode plan --packet "add authentication middleware" > context.json
  ```
</ParamField>

<ParamField path="--max-tokens" type="integer" default="8000">
  Maximum token budget for the context graph. Kode scores nodes by relevance and trims the graph from the bottom up until it fits within this limit.

  ```bash theme={null}
  kode plan --max-tokens 16000 "large cross-cutting refactor"
  ```
</ParamField>

## Examples

```bash theme={null}
# Human-readable summary of the context graph
kode plan "add authentication middleware"

# Emit a context packet and save it for later
kode plan --packet "refactor auth" > context.json

# Count how many nodes are in the dependency graph
kode plan --graph "fix the user service" | jq '.nodes | length'

# Expand the context budget for a large task
kode plan --max-tokens 16000 "migrate database layer to new schema"
```

## Typical workflow: plan then loop

Running `kode plan --packet` before a generation command is the most reliable way to handle multi-file tasks. The packet gives the LLM precise, AST-grounded context instead of a raw directory listing.

```bash theme={null}
# Step 1: build the context packet
kode plan --packet "add pagination to user list endpoint" > ctx.json

# Step 2: run the full pipeline with surgical context
kode loop --context-file ctx.json "add pagination to user list endpoint"
```

You can do the same with `kode run`:

```bash theme={null}
kode plan --packet "add input validation" > ctx.json
kode run --context-file ctx.json "add input validation to CreateUser handler"
```

## Human-readable output

When run without `--graph` or `--packet`, `kode plan` prints a summary like this:

```
── Context Graph Summary ────────────────────────────
  ✓  Nodes: 14  |  Edges: 22  |  Tokens: 3841 / 8000

── Files ────────────────────────────────────────────
  internal/user/handler.go
  ├─ function: CreateUser [high]
  ├─ function: validateUserInput [high]
  internal/user/service.go
  ├─ function: CreateUserService [medium]
  internal/middleware/auth.go
  ├─ function: AuthMiddleware [high]

── Plan Steps ───────────────────────────────────────
  Step 1: Add middleware to router
    internal/router/router.go
  Step 2: Implement auth validation logic
    internal/middleware/auth.go
```

<Tip>
  Use `--max-tokens` to expand the context for large tasks (for example `--max-tokens 16000`). Larger contexts improve recall on cross-cutting changes but cost proportionally more tokens. For most single-feature tasks, the default 8,000-token budget is sufficient.
</Tip>