ValarMind Code

Multi-agent CLI for software development, inspired by Claude Code CLI and Codex CLI. Each step of the development process is handled by a specialist agent.

Status: Phase 1-8 implemented — Foundation through Architecture Evolution. BPE token counting, gradual prompt truncation, parallel tool execution, result caching, repo map caching, plan checkpointing.

Features

• 9 Specialist Agents - Orchestrator, Search, Research, Code, Review, Test, Docs, QA, Init
• Hierarchical Orchestration - Orchestrator coordinates agents with specific permissions and tools
• Automatic Quality Gates - Review and QA required for risky code
• Local Memory - Short-term (session) and medium-term (VALARMIND.md, state.json)
• TOON Compaction - Up to 40% token savings
• Hybrid Plugins - MCP for external tools + native plugins for deep integration
• OpenRouter - Access to multiple models (OpenAI, Anthropic, Google) with a single API key

Agent Architecture

CLI

# Install
bun install -g valarmind-code

# Interactive mode
valarmind-code

# Single prompt
valarmind-code -p "Add logout button to navbar"

# Plan mode (no execution)
valarmind-code --plan -p "Implement user settings"

# Auto-approve in sandbox
valarmind-code -y --sandbox -p "Run tests and fix failures"

Commands

Slash Commands (REPL)

/init /compact /clear /help /exit /status /model /settings /plan /approve /reject /undo /diff /commit /agents /tasks

Configuration

~/.config/valarmind/
├── credentials.json     # API key (chmod 600)
└── config.json          # User preferences

<project>/
├── VALARMIND.md         # Project instructions (versioned)
├── VALARMIND.local.md   # Local preferences (gitignored)
└── .valarmind/
    ├── config.json      # Project config
    └── memory/
        ├── state.json   # Operational state
        └── state.toon   # Compact version

Plugins

MCP Servers

{
    "mcp": {
        "servers": {
            "postgres": {
                "command": "npx",
                "args": ["-y", "@modelcontextprotocol/server-postgres"],
                "env": { "DATABASE_URL": "${DATABASE_URL}" }
            }
        }
    }
}

Native Plugin Types

Documentation

Stack

Roadmap

Phase 1: Foundation

• TypeScript interfaces for agents
• Inter-agent communication protocol
• Basic Orchestrator with todo-list
• .valarmind/memory/ structure

Phase 2: Core Agents

• Search Agent
• Research Agent
• Init Agent
• Code Agent
• Test Agent

Phase 3: Quality Agents

• Review Agent (code review, security, performance, auto-fix loop)
• QA Agent (build, lint, typecheck, tests via bash)
• Docs Agent (documentation generation and maintenance)
• Agent registration (8 agents total)
• Result parser (balanced brace JSON extraction)
• Quality gates integration in Orchestrator

Phase 4: Integration

• PromptBuilder integration in AgentRunner (priority-based sections, token budget)
• TOON compaction verification
• Hook integration (PreToolUse, PostToolUse, SessionEnd, PreCompact)
• Streaming in REPL (AsyncIterable for direct answers)
• Plan mode (createPlan, executePendingPlan, rejectPendingPlan, updatePlanTask)
• New slash commands (/plan, /approve, /reject, /tasks, /undo, /diff, /commit)
• MetricsCollector (token tracking, invocations, errors per agent via EventBus)
• Integration tests (orchestrator flow, plan mode, hooks)

Phase 5: Web Search, Plugins & Deferred

• Web search via OpenRouter :online suffix (Research Agent uses model:online for real-time web grounding)
• Web fetch with Turndown HTML-to-Markdown + cache
• Tree-sitter repo map for structural code understanding (web-tree-sitter WASM)
• MCP Manager (stdio/StreamableHTTP transport)
• MCP tool bridge (namespace mcp__server__tool)
• Plugin Manager (HookPlugin, AgentPlugin, ProviderPlugin)
• Security sandboxing (per-agent profiles, macOS sandbox-exec, Linux bubblewrap)

Phase 6: Hardening & Bug Fixes

• Wire ModelRouter in container (agent-specific model routing via cost tiers)
• Fix SandboxManager.isAvailable() exit code verification
• Fix streaming plan leakage in processStream() (buffer before yield)
• Harden macOS sandbox (deny-default or migrate to @anthropic-ai/sandbox-runtime)
• Implement network restrictions on macOS (currently Linux-only)
• Add retry/circuit breaker to chatStream() streaming path
• Sanitize process.env before passing to hooks (filter secrets)
• Refactor AgentRunner constructor to deps object pattern
• Fix finish_reason: 'length' hardcoded write_file instruction
• Fix container shutdown() error handling (Promise.allSettled)
• Align types and documentation (permissions, timeouts, i18n)
• Improve TOON compactor (module caching, savings threshold for state)
• Fix streaming tool call accumulation across chunks

Phase 7: Test Coverage Expansion

• Integration tests for CLI REPL (slash commands, session lifecycle)
• Authentication flow tests (first-run, validation, credentials)
• Unit tests for individual tools (glob, grep, bash, edit, read, write)
• Error scenario tests (network timeout, permission denied, malformed)
• Sandbox execution tests (real command wrapping, deny rules)

Phase 8: Architecture Evolution

• Real token counter (gpt-tokenizer BPE replacing char-based heuristic)
• PromptBuilder gradual truncation (partial sections instead of binary drop)
• Model-aware cache control (Anthropic-only via OpenRouter)
• Repo map caching with file-hash invalidation
• Parallel tool execution for read-only I/O-bound tools
• Semantic tool result caching between agents in same plan
• Plan execution checkpointing (resume-from-failure)
• MCP spec updates (Tool Output Schemas, Elicitation, Resource Indicators)
• IDE integration (VS Code extension or Language Server mode)

Future (not planned)

• LSP integration via MCP (Serena pattern — user installs language-specific MCP servers)

References

• Model Context Protocol
• TOON Format
• OpenRouter