Ivo

Context-first CLI for AI coding agents.

Ivo helps you gather the right repository context fast: file tree, structural codemaps, keyword snippets, and saved context bundles you can pipe into your agent.

Why Use It

• Reduces prompt bloat by prioritizing relevant files.
• Supports multiple context strategies (keyword, skeleton, diff, graph, etc.).
• Saves reusable context snapshots with short IDs.
• Works well in terminal-first agent workflows.

Install

bun install

Run in dev mode:

bun run dev -- --help

Build a standalone binary:

bun run build
./dist/ivo --help

Quick Start

# 1) Understand structure
ivo tree --depth 3
ivo structure src

# 2) Build task-focused context
ivo context "auth, session, jwt, token"

# 3) Fetch saved context by ID and pipe to your agent
ivo get <id> --raw | codex exec -

Core Commands

• ivo tree
  Print workspace tree.

• ivo search <pattern>
  Search code or paths.

• ivo structure [paths...]
  Extract codemaps (functions, classes, types, imports).

• ivo select <list|add|set|remove|clear> [paths...]
  Manage manual file selection.

• ivo context [keywords]
  Build context for a task. Saves by default; use --full to print inline.

• ivo bucket [keywords]
  Advanced context planning with strategy controls and budget caps.

• ivo get [id]
  List and retrieve saved contexts.

• ivo recipe <save|run|list|show|delete>
  Store reusable context presets.

• ivo index / ivo map
  Build embedding index and inspect semantic clusters.

Strategy-Based Context

ivo bucket can combine:

• inventory: repo tree snapshot
• skeleton: entrypoints and structural files
• keyword: snippet matches for search terms
• symbols: codemaps for matched files
• config: config/build files
• diff: git-changed files
• graph: import-graph neighbors
• ast: codemap-heavy keyword analysis
• complexity: large/complex files
• docs: markdown and docs files
• forest: external knowledge graph (if forest CLI is installed)
• apple-notes: snippets from Apple Notes export JSON
• discord: snippets from Discord export JSON

External adapter paths:

• Apple Notes: IVO_APPLE_NOTES_FILE or .ivo/adapters/apple-notes.json
• Discord: IVO_DISCORD_FILE or .ivo/adapters/discord.json

Configuration

Ivo loads config from:

• Global: ~/.config/ivo/config.json
• Project: .ivo/config.json (overrides global)

Interactive setup:

ivo setup

You can configure:

• LLM endpoint/model for query expansion and operator features.
• Default budget, intensity, and output format.
• Embedding provider/model settings.

Saved Contexts

By default, ivo context and ivo recipe run save outputs in:

• .ivo/contexts/<id>.xml
• .ivo/contexts/<id>.meta.json

Useful retrieval commands:

ivo get --list
ivo get <id>
ivo get <id> --meta
ivo get <id> --raw
ivo pin <id>
ivo unpin <id>

Embeddings and Semantic Map

Build an embedding index:

ivo select set src
ivo index

Show semantic clusters:

ivo map
ivo map --label

Development

bun run typecheck
bun run build

Project is TypeScript + Bun + Commander + Tree-sitter.
Main entrypoints:

• src/cli.ts (CLI)
• src/index.ts (library export)
• src/slicer/ (strategy engine)
• src/codemap/ (AST extraction)
• src/commands/ (command handlers)