veda-ts

A CLI oracle your coding agent consults for planning and review.

Motivation

Frontier intelligence is ridiculously priced

Frontier models are expensive. Fable 5 runs at $10/$50 per million tokens. Sol runs at $5/$30. K3 runs at $3/$15. These are the models you want for planning, debugging, and review. They are too expensive to drive every token of every coding session.

Instead, use an economical agent like DeepSeek V4 ($0.14/$0.28) or GLM 5.2 ($1.40/$4.40) as your main driver in the harness of your choice (Claude Code, Codex, Pi, or any agent that can shell out to a CLI). Then ask it to use veda to consult the expensive models only when it matters.

The driver writes the code. Veda brings in frontier intelligence only where it earns its cost.

Veda is that consultation channel. It wraps codex, claude-code, droid, pi, and agy (Google Antigravity CLI) behind personas (navigator-plan, navigator-chat, reviewer, worker).

Heavy thinking, based on a few academic papers

Some problems are too hard for one call. Architectural design, subtle bugs, decisions with no clear answer. You want several independent attempts that converge on the right answer.

Veda's deep mode runs parallel solvers, each using a different strategy. A judge picks the best answer. A verifier kicks in when confidence is low. This is a homegrown Deepthink, inspired by:

• Self-Consistency: sample diverse reasoning paths, aggregate the best
• Universal Self-Consistency: use an LLM as judge to select among candidates
• Chain-of-Verification: fact-check outputs before finalizing

Quick Start

Prerequisites

• A backend CLI, installed and authenticated:
  • codex, claude-code, pi, droid, or agy (brew install --cask antigravity-cli, then authenticate once with an interactive agy session)

Quick Start

# 1. Install
npm install -g veda-ts

# 2. Run in your project
cd your-project
veda init                          # first-time setup: installs agent skills for pi/codex/claude

# 3. Hand a hard problem to your driver agent through a skill
#
#    After `veda init`, your agent (pi / codex / claude) auto-discovers the
#    bundled skills. The two you'll reach for most:
#      /veda:plan                — align on a plan with the Navigator (no execution)
#      /veda:plan-and-implement  — align, then carry out the plan
#
#    Pretend: a multi-tenant API needs a rate limiter — fairness, burst
#    tolerance, Redis vs in-memory tradeoffs. Type the slash command; your
#    agent shares your code and drives veda under the hood:
#
#      /veda:plan design a per-tenant rate limiter (fairness, burst tolerance, Redis vs in-memory)
#
#    Iterate with /veda:plan until the plan holds up, then ship it:
#
#      /veda:plan-and-implement the rate-limiter plan

After veda init, your driver agent (pi, codex, or claude) auto-discovers the bundled skills (veda-plan, veda-plan-implement, veda-plan-implement-review, veda-deep-plan, veda-worker) and can invoke veda on its own. Run veda skills list to verify they installed.

git clone https://github.com/kennyfrc/veda.git
cd veda/veda-ts
bun install && bun run build
cp dist/veda ~/.local/bin/

Install Agent Skills

Veda bundles five Agent Skills (veda-plan, veda-plan-implement, veda-plan-implement-review, veda-deep-plan, veda-worker) that teach coding agents how to collaborate with the Navigator / Reviewer models. One command installs them into the directories read by Pi, OpenAI Codex CLI, and Claude Code:

veda skills install     # writes ~/.agents/skills/ + symlinks ~/.claude/skills/
veda skills list        # show install status and symlink health
veda skills uninstall   # remove them

veda init runs skills install as part of first-time setup. The skills travel inside the compiled veda binary as embedded assets, so install needs nothing on disk except the binary. See .agents/skills/README.md for the full discovery layout.

How-To Guides

Manage File Selection

export VEDA_SESSION=my-session

veda sel add "src/*.ts"           # Add files (quote globs)
veda sel add main.ts:10-50        # Add line range (1-indexed)
veda sel ls                       # List with token counts
veda sel rm main.ts               # Remove file and all its slices
veda sel clear                    # Clear all

Use Different Backends

veda -b codex "..."        # OpenAI Codex (default)
veda -b claude-code "..."  # Anthropic Claude Code
veda -b droid "..."        # Factory Droid (droid exec)
veda -b pi "..."          # pi CLI (any provider/model from ~/.pi/agent/models.json)
veda -b agy "..."         # Google Antigravity CLI (agy headless mode)

Note on reasoning configuration:

• Codex: Uses native model_reasoning_effort flag. The --reasoning flag works as expected.
• Claude Code: Maps --reasoning levels to the MAX_THINKING_TOKENS environment variable automatically.
• pi CLI: Maps --reasoning to pi's --thinking flag and --sandbox to pi's --tools flag. Supports any provider/model defined in ~/.pi/agent/models.json.
• Droid: Maps --reasoning to -r flag and --sandbox to --auto flag. Supports any model available to droid exec. Droid has no true zero-tool switch (--enabled-tools '' is parsed as "no restriction" and --disabled-tools '*' is rejected), so the no-tools policy passes --disabled-tools with the full tool-id list (verified to block tool calls in a live probe) plus the no-tools notice in the system prompt. The list is pinned in DROID_ALL_TOOL_IDS; a droid release that adds tools makes runs fail loudly with "Unknown tool identifier(s)" — refresh the list from droid exec --list-tools then.
• agy: Maps --reasoning to --effort low|medium|high (six veda levels clamp: minimal/low→low, high/xhigh/max→high). Capability-suffixed slugs like gemini-3.1-pro-high encode their own effort, so --effort is omitted for those. Tool policy is advisory: agy has no per-run tool allowlist, so persona tool limits ride in the system prompt and agy's permission rules arbitrate. --sandbox full maps to --dangerously-skip-permissions; read-only and workspace-write use agy's defaults (workspace file writes are auto-allowed; shell commands soft-deny). veda resume continues agy conversations by explicit conversation id. Models: agy models lists valid slugs (gemini-3.1-pro-high, claude-sonnet-4-6, ...); an unknown slug fails loudly.

Use Model Aliases

Model aliases auto-select the correct backend:

# Claude models (→ claude-code backend)
veda -m opus "..."      # Uses claude-code with opus
veda -m sonnet "..."    # Uses claude-code with sonnet
veda -m haiku "..."     # Uses claude-code with haiku

# OpenAI models (→ codex backend)
veda -m sol "..."       # Uses codex with gpt-5.6-sol (high)
veda -m terra "..."     # Uses codex with gpt-5.6-terra (high)
veda -m luna "..."      # Uses codex with gpt-5.6-luna (high)


# pi models (→ pi backend, auto-inferred from pi/ prefix)
veda -m pi/wafer/glm-5.1 "..."                        # wafer provider
veda -m pi/fireworks/accounts/fireworks/routers/kimi-k2p6 "..."  # fireworks provider
veda -m pi/neuralwatt/moonshotai/Kimi-K2.6 "..."      # neuralwatt provider

# Antigravity models (→ agy backend)
veda -m gemini-pro "..."          # Uses agy with gemini-3.1-pro-high
veda -m gemini-flash "..."        # Uses agy with gemini-3.6-flash-high
veda -m agy/gemini-3.6-flash-low "..."  # agy/ prefix auto-infers the agy backend
veda -b agy -m claude-sonnet-4-6 "..."  # agy-hosted Claude (needs explicit -b; bare claude-* goes to claude-code)

When you specify both -b and -m, the model is passed literally (no alias resolution).

User-defined aliases. Add your own aliases to ~/.config/veda/config; they override the built-in table and work everywhere -m works (base persona, worker, and deep-mode solver/judge/verifier/revision slots):

# ~/.config/veda/config — comma-separated name=full-model[:reasoning]
MODEL_ALIASES="flash=pi/neuralwatt/deepseek-v4-flash"

veda -m flash "..."        # → pi backend, pi/neuralwatt/deepseek-v4-flash

Note: The --reasoning flag (-r) is fully supported by the Codex backend, automatically configured for the Claude backend (mapped to MAX_THINKING_TOKENS), and supported by the Gemini backend (via scoped settings.json override with automatic cleanup).

Discover Models

veda models answers "what can I type after -m?" for each installed backend — the effective default (with its source), the aliases that route to it, and a capped catalog. Default output is fully offline (local files only); pi and droid collapse variant lineage into family heads so 45-row configs stay readable.

veda models              # all installed backends: default + aliases + capped catalog
veda models pi           # one backend, uncapped: full discoverable inventory
veda models --json       # machine-readable (warnings inside the JSON)
veda models --refresh    # live-probe codex + agy for this run; falls back soft

Claude and droid have no live listing command, so their built-ins are curated and labeled as such. --refresh only live-queries the two backends that support it (codex debug models, agy models) and writes nothing.

Resume Conversations

veda -S agent-1 "Design a distributed lock"
veda -S agent-1 resume "What about fairness?"
veda -S agent-1 resume -- "--explain flags"  # Prompt with dashes

Use Deep Thinking Mode

veda deep "Complex design question"           # 3 solvers, verification on
veda deep -k 5 "Critical architecture"        # 5 solvers
veda deep --no-verify "Quick comparison"      # Skip verification
veda deep --trace /tmp/trace.yaml "..."       # Save trace for debugging
veda deep --json "..." | jq '.candidates'     # JSON output

# Per-stage model/backend overrides (mixed providers)
veda deep --solver-model opus --judge-model gpt "..."
veda deep --solver-backend claude-code --verifier-backend codex "..."

Backend/Model Precedence:

The -b and -m flags apply to all stages (solver, judge, verifier, revision) unless overridden by per-stage flags:

# All stages use codex:gpt-5.2
veda deep -b codex -m gpt-5.2 "..."

# All stages use codex:gpt-5.2, except judge uses claude-code:opus
veda deep -m gpt-5.2 --judge-model opus "..."

# -m infers backend from model: opus → claude-code for all stages
veda deep -m opus "..."

Precedence order (highest to lowest):

1. Per-stage CLI flags (--judge-model, --verifier-backend, etc.)
2. Base CLI flags (-b, -m): applies to all stages
3. Config file stage defaults (DEEP_JUDGE_MODEL, etc.): only when no -b/-m
4. Global defaults

Reasoning Precedence:

The -r flag also applies to all stages (solver, judge, verifier, revision) unless overridden by per-stage flags:

# All stages use high reasoning
veda deep -r high "Complex analysis"

# All stages use high, except verifier uses xhigh
veda deep -r high --verifier-reasoning xhigh "..."

# Per-stage reasoning flags (no -r)
veda deep --solver-reasoning medium --judge-reasoning high "..."

Precedence order (highest to lowest):

1. Per-stage CLI flags (--solver-reasoning, --judge-reasoning, etc.)
2. Base CLI flag (-r): applies to all stages
3. Config file stage defaults (DEEP_SOLVER_REASONING, etc.): only when no -r
4. Stage defaults (solver: medium, judge: medium, verifier: high, revision: high)

Distribute solvers across multiple backends:

# Even distribution: 2 solvers per backend (k=6, 3 backends)
veda deep -k 6 --distribute-solvers "Complex problem"
veda deep -k 6 --distribute-solvers --solver-backends claude-code,codex,droid "Custom backends"

Order is deterministic: explicit --solver-backends is normalized (trim/lowercase/dedup) and sorted before round-robin.

Note: -m cannot be used with --distribute-solvers across multiple backends (use --solver-model instead).

Listed mode: compare specific models on the same prompt:

# One solver per model; every solver gets the identical prompt (no module rotation)
veda deep --solver-models sol,k3,fable "Design a rate limiter"

# Zip a reasoning module onto each slot, positionally
veda deep --solver-models sol,k3 --modules analytical/causal_analysis,systematic/systems_thinking "..."

Each entry resolves through the alias/prefix machinery, so backend, model, and per-alias reasoning are pinned per slot (--solver-reasoning overrides all slot hints). Roster size is the list length (-k may only confirm it). Repeat entries to duplicate a model (sol,sol,k3). Conflicts with -m, --solver-model, --solver-backend(s), --distribute-solvers, --categories, --uniform, and --low-count-modules. Config equivalent: DEEP_SOLVER_MODELS=sol,k3,fable.

Use Personas

veda -p navigator-plan "..."        # Plan + program-design protocol (high)
veda -p navigator-chat "..."        # Discussion (medium reasoning)
veda -p reviewer "..."             # Code review — P0/P1/P2 findings (medium reasoning, no tools)
veda -p worker "..."                # Execute an implementation task (writes your repo)
veda personas                      # List available

The Worker persona (write-capable)

The worker is veda's first write-capable seat. It inverts the advisory personas' defaults — tools: all and sandbox: full — and is meant for bounded implementation tasks a Driver can fully specify.

# Delegate an implementation task; tools on, full sandbox
veda -S feat-42 -p worker "Implement slice 1 of design.json; run the slice tests"

# -m semantics are identical to every other persona
veda -S feat-42 -p worker -m opus "Apply the auth fix from design.json"

Every worker run ends with a mandatory <worker_report> block (Factory's subagent handoff contract) parsed by veda into report.yaml in the session dir — <project>/.veda/sessions/<session>/report.yaml (project-local; ~/.config/veda/sessions/ outside a git repo) — alongside the full raw transcript response.yaml. A Driver (often another agent) branches on report.yaml:

STATUS=$(yq '.status' "$(git rev-parse --show-toplevel)/.veda/sessions/feat-42/report.yaml")
case "$STATUS" in
  completed) veda -S feat-42 -p reviewer "Review the diff against design.json" ;;
  blocked)   veda -S feat-42 resume "$(yq '.needs' .../report.yaml)" ;;
  failed)    # route discovered_issues back to navigator-plan ;;
esac

Because the worker edits your repo by default, its run header shows the sandbox mode up front, and --sandbox read-only is always available to run it as a dry-run planner (a report with no edits). The worker stays in scope: tools on, full sandbox — both overridable via --tools/--no-tools and --sandbox.

This orchestration workflow is bundled as the veda-worker agent skill (from the caller's point of view: you orchestrate plan → one worker run → verify; the worker drives the implementation). Install it with veda skills install.

The Reviewer persona

The reviewer reviews a patch — the git diff plus the selected file context — and reports only discrete, actionable findings grouped by severity (P0 must fix, P1 should fix, P2 consider). It runs with no tools: it reviews the diff/context and design.json (auto-attached) it is given, and names any missing artifact rather than searching for it.

git diff > /tmp/changes.diff
veda -S feat-42 sel add /tmp/changes.diff
veda -S feat-42 -p reviewer "Review the diff against the design; report P0/P1/P2 findings"

The reviewer ends with a verdict line the orchestrator branches on: review: pass (no P0/P1 findings) or review: needs-fix (P0/P1 present — route them back to the worker). This drives a review → fix → re-review loop: fix P0/P1 findings, regenerate the diff, and re-review until pass (P2 may stay open).

Architecture

Architecture

Core Primitives

The library uses data-oriented primitives (plain data structs with standalone functions):

LLM Call: Single model invocation

interface LlmRequest {
  backend: string;
  prompt: string;
  context?: string;
  systemPrompt: string;
  model?: string;
  reasoning?: 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max';
  sandbox?: 'read-only' | 'workspace-write' | 'full';
}

// Usage
const response = await runLlm(request);
console.log(response.text, response.usage);

Ensemble: Parallel LLM calls

const result = await runEnsemble([
  { id: 'solver-1', request: { backend: 'codex', prompt, systemPrompt: '...' } },
  { id: 'solver-2', request: { backend: 'codex', prompt, systemPrompt: '...' } },
]);
console.log(result.successful); // Array of response texts

Judge: Select best candidate

const result = await runJudge({
  backend: 'codex',
  systemPrompt: JUDGE_SYSTEM_PROMPT,
  candidates: ['Answer A', 'Answer B', 'Answer C'],
  originalTask: 'What is 2+2?',
});
console.log(result.selected, result.decision.confidence);

Verification: Chain-of-Verification for fact-checking

const result = await runVerification({
  backend: 'codex',
  systemPrompt: VERIFIER_SYSTEM_PROMPT,
  type: 'reasoning',
  draft: 'The answer is 42',
  originalTask: 'What is the meaning of life?',
});
console.log(result.checks, result.results, result.revision);

Deep Thinking Pipeline

┌─────────────┐
│   Prompt    │
└──────┬──────┘
       ▼
┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│  Solver 1   │    │  Solver 2   │    │  Solver 3   │  (parallel, diverse strategies)
└──────┬──────┘    └──────┬──────┘    └──────┬──────┘
       └──────────────────┼──────────────────┘
                          ▼
                 ┌─────────────────┐
                 │      Judge      │  (select best candidate)
                 └────────┬────────┘
                          ▼
                 ┌─────────────────┐
                 │    Verifier     │  (if confidence < 70%)
                 └────────┬────────┘
                          ▼
                 ┌─────────────────┐
                 │     Answer      │
                 └─────────────────┘

Verification triggers when:

• Judge confidence is below 70% (medium or low)

Reasoning Modules

Each solver uses a different cognitive strategy from 8 categories. Modules are sourced from Polya's "How to Solve It", Hamming's "Art of Doing Science and Engineering", and McKinsey problem-solving frameworks.

| Category | Focus | Example Modules | |----------|-------|-----------------| | analytical | Critical thinking, root cause analysis | so_what_test, eighty_twenty_focus, causal_analysis | | creative | Novel solutions, reframing | invert_the_problem, first_principles, radical_rethinking | | systematic | Structured decomposition | mece_decomposition, issue_tree, working_backward | | strategic | Planning, hypothesis-driven | hypothesis_first, analogical_transfer, planning | | evaluative | Risk assessment, tradeoffs | risk_assessment, check_completeness, tradeoff_analysis | | contextual | Stakeholder analysis, constraints | stakeholder_analysis, resource_constraints | | empirical | Evidence-based validation | experimental_design, historical_analysis, data_driven | | reflective | Meta-cognition, success criteria | reflective_thinking, success_criteria, decision_under_uncertainty |

# By category (random module from each)
veda deep --categories analytical,evaluative "Should we use microservices?"

# Exact modules with category/id format
veda deep --modules analytical/so_what_test,systematic/mece_decomposition "Analyze design"

# Mix exact and random: exact analytical, random creative, exact systematic
veda deep --modules analytical/so_what_test,creative,systematic/working_backward "Complex question"

Backends

Each backend normalizes to a common Message stream:

interface Message {
  type: 'init' | 'text' | 'reasoning' | 'tool_use' | 'tool_result' | 'error' | 'done';
  content?: string;
  sessionId?: string;
  usage?: { inputTokens: number; outputTokens: number };
}

Sessions

Sessions isolate state between concurrent agents:

• File selection: <project>/.veda/sessions/<id>/selection (global fallback ~/.config/veda/sessions/)
• Thread info: <project>/.veda/sessions/<id>/thread.json (global fallback ~/.config/veda/sessions/)

Reference

CLI Options

veda [options] <prompt>
veda sel <add|rm|ls|clear|tokens> [args]
veda skills <install|uninstall|list>
veda resume [prompt]
veda deep [options] <prompt>

Options:
  -S, --session <id>     Session ID (or VEDA_SESSION env)
  -p, --persona <name>   navigator-plan|navigator-chat|reviewer|worker
  -b, --backend <name>   codex|claude-code|droid|pi|agy
  -m, --model <model>    Model or alias (opus|sonnet|haiku|gpt|glm-5.2|makora|pi/<provider>/<model-id>)
  -r, --reasoning <lvl>  minimal|low|medium|high|xhigh|max
  -k <n>                 Solver count for deep mode (default: 3, max: 8)
  --categories <list>    Reasoning categories (comma-separated)
  --modules <list>       Module specifiers: category/id, category, or id
  --no-verify            Skip verification in deep mode
  --trace <file>         Save trace to YAML file
  --no-sel               Ignore selection
  --json                 JSON output
  -o, --output <file>    Save to file

Deep Mode Stage Overrides:
  --solver-backend <name>   Backend for solvers
  --solver-model <model>    Model for solvers
  --judge-backend <name>    Backend for judge
  --judge-model <model>     Model for judge
  --verifier-backend <name> Backend for verifier
  --verifier-model <model>  Model for verifier

Project Structure

src/
├── core/          # Deep primitives (llm, ensemble, judge, verify, modules)
├── backend/       # codex.ts, claude.ts, droid.ts, pi.ts, agy.ts
├── pipelines/     # deep-think.ts (orchestration)
├── context/       # Selection and slice management
├── conversation/  # Thread persistence
├── agent/         # Config and persona loading
├── commands/      # CLI handlers
└── cli.ts         # Argument parsing

Configuration

~/.config/veda/config:

# Default backend
BACKEND="pi"
PERSONA="navigator-chat"

# User-defined model aliases (comma-separated name=full-model[:reasoning])
MODEL_ALIASES="flash=pi/neuralwatt/deepseek-v4-flash"

# Per-backend model and reasoning settings
CODEX_MODEL="gpt-5.2"
CODEX_REASONING="medium"     # Uses native -c model_reasoning_effort flag

CLAUDE_CODE_MODEL="opus"
# CLAUDE_CODE_REASONING is mapped to MAX_THINKING_TOKENS env variable:
#   minimal → 0 (disabled)
#   low → 7999 (8k-1 tokens)
#   medium → 15999 (16k-1 tokens)
#   high → 31999 (32k-1 tokens)
#   xhigh → 63999 (64k-1 tokens)
#   max → 63999 (64k-1 tokens)

# Gemini 3.x: Maps --reasoning to thinkingLevel (LOW|MEDIUM|HIGH)

DROID_MODEL="custom:Makora-GLM-5.2-NVFP4-9"
DROID_REASONING="medium"
# Droid: Maps --reasoning to -r flag, --sandbox to --auto flag
#   minimal → off
#   low → low
#   medium → medium
#   high → high
#   xhigh → high
#   max → max

PI_MODEL="pi/wafer/glm-5.1"
# pi CLI: Maps --reasoning to --thinking flag (off|minimal|low|medium|high|xhigh|max)
#   minimal → minimal
#   low → low
#   medium → medium
#   high → high
#   xhigh → xhigh
#   max → max
# Gemini 2.x: Maps --reasoning to thinkingBudget (tokens)
#   minimal → 8192 (same as low)
#   low → 8192
#   medium → 16000
#   high → 32000
#   xhigh → 32000

# Deep mode stage defaults (overridden by -b/-m CLI flags)
DEEP_DISTRIBUTE_SOLVERS="true"
DEEP_SOLVER_BACKENDS="pi"
DEEP_JUDGE_BACKEND="pi"
DEEP_JUDGE_MODEL="pi/wafer/glm-5.1"
DEEP_VERIFIER_BACKEND="pi"
DEEP_VERIFIER_MODEL="pi/wafer/glm-5.1"
DEEP_REVISION_BACKEND="pi"
DEEP_REVISION_MODEL="pi/wafer/glm-5.1"

Development

bun test              # Run tests
bun run typecheck     # Type check
bun run build         # Compile to dist/veda
bun run dev -- args   # Run without compiling

License

MIT