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/pi-kota@v0.1.0

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.