pi-kota

Code intelligence that doesn't eat your context window.

A pi extension that gives your coding agent a persistent, dependency-aware brain for TypeScript and JavaScript repos — powered by KotaDB over MCP, with built-in context pruning to keep long sessions sharp.

✨ What It Does

| Problem | pi-kota's Answer | |---------|-----------------| | Agent repeatedly reads large files to answer "what depends on X?" | kota_deps — instant dependency graph from a persistent index | | 30-turn sessions bloat with stale tool output | Context pruning removes old payloads, preserves meaning + rehydration paths | | Impact analysis requires the agent to trace imports manually | kota_impact — change impact summary, pinned so it survives pruning | | Large tool results blow up the context budget | Automatic truncation + blob cache — full output recoverable on demand |

The Short Version

KotaDB = persistent code index (deps, symbols, usages, impact)
pi-kota = thin wrapper + context governor (bounded output, pruning, blob cache)

You get fast, bounded queries over your codebase without raw file dumps accumulating in the conversation.

🔧 Tools

Six curated tools, all output-bounded by default:

| Tool | What It Does | |------|-------------| | kota_index | Index or re-index the current repository (no prompt) | | kota_search | Code search — paths, compact, or snippet output modes | | kota_deps | Dependency graph queries (dependents, dependencies, or both) | | kota_usages | Find all usages of a symbol across the repo | | kota_impact | Analyze change impact — risk surface, affected files, recommended tests | | kota_task_context | Summarize deps + impact for a set of files (great for task planning) |

⌨️ Commands

| Command | Description | |---------|-------------| | /kota status | Show process state, repo root, index status, config sources | | /kota index | Trigger indexing (asks for confirmation if enabled) | | /kota evict-blobs | Evict old/oversized blob-cache entries (best-effort) | | /kota restart | Reset KotaDB connection (next tool call reconnects) | | /kota reload-config | Reload config from disk |

🧹 Context Governance

pi-kota prevents context bloat through two layers:

1. LLM Context Pruning (context event)

• Keeps the last N turns intact (default: 2)
• Older read, bash, and kota_search results get replaced with compact rehydration pointers
• Adaptive mode tightens pruning when token usage climbs

2. Tool Result Truncation (tool_result event)

• Large kota_* outputs are truncated to maxToolChars
• Full output saved to blob cache (~/.pi/cache/pi-kota/blobs/)
• Blob ID included in the truncated result for recovery

📦 Prerequisites

pi-kota spawns KotaDB via Bun:

bun --version    # required

npm install runs a non-blocking Bun availability check (scripts/check-bun.js) and prints PATH guidance if Bun is missing.

Bun PATH troubleshooting

If startup fails with:

pi-kota: 'bun' not found on PATH

Install Bun and ensure your shell PATH includes Bun's bin directory (usually ~/.bun/bin).

🚀 Install

As a pi package (recommended)

# Global install (default) — available in all pi projects
pi install git:github.com/coctostan/pi-kota

# Project-local install — only for the current repo (writes to .pi/settings.json)
pi install -l git:github.com/coctostan/pi-kota

By default, pi install is global and adds the package to ~/.pi/agent/settings.json. Use -l for a project-local install (adds it to .pi/settings.json).

For reproducible installs, you can optionally pin to a git tag (or commit SHA), for example:

pi install -l git:github.com/coctostan/[email protected]

After npm publish, you'll also be able to install by package name:

pi install pi-kota

You can also edit the settings file manually:

{
  "packages": ["git:github.com/coctostan/pi-kota"]
}

Local development

Clone the repo and install dependencies:

git clone https://github.com/coctostan/pi-kota.git
cd pi-kota
npm install

Then point pi at the extension entry point from the project where you want to use it (e.g. in .pi/settings.json):

{
  "extensions": ["../pi-kota/src/index.ts"]
}

⚙️ Configuration

Config files are layered — global defaults, then project overrides:

| Scope | Path | |-------|------| | Global | ~/.pi/agent/pi-kota.json | | Project | .pi/pi-kota.json |

Default Config

{
  "kota": {
    "toolset": "core",
    "autoContext": "off",
    "confirmIndex": true,
    "connectTimeoutMs": 10000,
    "command": "bun",
    "args": ["x", "kotadb@next", "--stdio", "--toolset", "core"]
  },
  "prune": {
    "enabled": true,
    "keepRecentTurns": 2,
    "maxToolChars": 1200,
    "adaptive": true
  },
  "blobs": {
    "enabled": true,
    "dir": "~/.pi/cache/pi-kota/blobs",
    "maxAgeDays": 7,
    "maxSizeBytes": 52428800
  },
  "log": {
    "enabled": false,
    "path": "~/.pi/cache/pi-kota/debug.jsonl"
  }
}

Key Options

| Option | Default | Description | |--------|---------|-------------| | kota.autoContext | "off" | Auto-inject task context: "off", "onPaths" (1–3 file paths in prompt), "always" | | kota.confirmIndex | true | Prompt before indexing when running /kota index (and other confirmation-based flows). Note: kota_index tool does not prompt. | | kota.connectTimeoutMs | 10000 | Connection timeout in milliseconds for Kota MCP startup | | prune.keepRecentTurns | 2 | Turns to keep intact before pruning | | prune.maxToolChars | 1200 | Max chars per tool result before truncation | | prune.adaptive | true | Tighten pruning when context usage is high | | blobs.enabled | true | Save full truncated outputs to blob cache | | blobs.dir | "~/.pi/cache/pi-kota/blobs" | Blob cache directory | | blobs.maxAgeDays | 7 | Evict blobs older than this (used by /kota evict-blobs) | | blobs.maxSizeBytes | 52428800 | Evict oldest blobs until cache is under this size (used by /kota evict-blobs) | | log.enabled | false | Enable debug JSONL logging (best-effort, never crashes the extension) | | log.path | "~/.pi/cache/pi-kota/debug.jsonl" | Debug log file path |

🛠️ Development

npm install
npm test
npm run test:e2e
npm run typecheck

Architecture

src/
├── index.ts          # Extension entry — events, commands, tool registration
├── runtime.ts        # Runtime state + path normalization
├── config.ts         # Layered config loading (global + project)
├── prune.ts          # Context pruning logic + adaptive settings
├── autocontext.ts    # Auto task-context injection rules
├── blobs.ts          # Blob cache writes
├── paths.ts          # File path extraction from prompts
├── text.ts           # Text truncation utilities
├── toolResult.ts     # Tool result truncation decisions
└── kota/
    ├── mcp.ts        # MCP stdio client (KotaDB connection)
    ├── tools.ts      # Budgeted tool calls + name mapping
    ├── schemas.ts    # TypeBox schemas for kota_* tool params
    └── ensure.ts     # Index confirmation flow

Design Reference

See docs/design.md for design background (draft; README + src/* are the source of truth for shipped behavior).

🙏 Attribution

pi-kota is built on top of KotaDB, created by Nico Bailon. Big thanks to Nico for designing and maintaining the code intelligence engine that powers this extension.

📄 License

MIT — see LICENSE for details.