Overarch CLI v0.5.0

The Learning Agent for Autonomous Software Engineering
Understand • Investigate • Plan • Execute • Verify • Learn
2026 Made By Yatharth Roy, From The Thursday AI Company of New Delhi

Overarch CLI is an autonomous, terminal-native AI coding agent built for real-world software engineering. Designed with senior-developer minimalism and strict human control, Overarch operates directly inside your terminal, learning from its mistakes and compounding engineering knowledge over time.

What's New in v0.5.0 ("The Learning Agent")

• Terminal-Native Focus: All web servers and webviews have been eliminated. Overarch CLI is 100% focused on the terminal developer experience.
• Persistent Learning Engine (src/learning/):
  • Project Memory (.overarch/memory/project.json): Tracks architecture notes, conventions, build/test commands, and tech stacks.
  • User Memory (~/.overarch/user_memory.json): Remembers user coding preferences, workflows, and stylistic rules.
  • Episodic Lessons (.overarch/memory/lessons.json): Automatically captures problem ➔ investigation ➔ resolution ➔ lesson whenever self-corrections or user insights occur.
  • Selective Prompt Injection: Never blindly dumps memory. Retrieves token-budgeted, query-relevant context for each task.
  • Learning Commands: overarch memory show, overarch memory search <query>, overarch memory forget <id>, overarch learn "<lesson>".
• Claude-Like Contextual Thinking:
  • Dynamic thinking spinner with progressive adjectives: *Analyzing repository architecture...*, *Synthesizing change impact...*, *Investigating code paths...*, *Deliberating implementation plan...*, *Distilling project memory...*
• Streamlined Status & Reduced Noise:
  • Eliminated redundant turn reports and mission cards during read-only interactions.
  • Clean, minimal diffs and one-line summaries only when modifications occur.
• Petdex Floating Desktop Companion (OverarchCompanion.exe):
  • Zero Focus Stealing: Transparent, frameless, always-on-top desktop companion built in native C# WPF using WS_EX_NOACTIVATE, WS_EX_TOPMOST, and WS_EX_TOOLWINDOW to ensure it never interrupts typing or terminal work.
  • Petdex Ecosystem Integration: Directly discovers, loads, and switches pets from ~/.petdex/pets/ and ~/.codex/pets/ (supports 8×9 and 8×11 sprite grids, WebP and PNG formats).
  • Real-Time Agent State Reactions: Visually reflects Overarch agent operations: idle (row 0), thinking/inspecting (row 8), editing/executing (row 7), waiting/approval (row 6), success (row 4), and error/warning (row 5).
  • Interactive Companion Controls: Right-click context menu to switch installed pets, install from Petdex, open terminal, or reposition. Left-click drag with edge snapping and position persistence (~/.overarch/companion_state.json).
  • Bundled Offline Default: Includes the official savage-codex-hacker pet definition and spritesheet for immediate out-of-the-box operation.
• Windows Native Integration:
  • Custom GUI Installer (dist-desktop/Overarch-Setup.exe): 10-step animated installer matching custom specifications (dark navy #081842, burgundy titlebar #5c1122, elapsed timer, collapsible log, Start Menu, Desktop, and PATH registration).
  • Console Launcher (dist-desktop/Overarch.exe): Lightweight C# native binary (< 75KB) launching Overarch CLI directly in Windows Terminal or cmd.
  • Companion Launcher (dist-desktop/OverarchCompanion.exe): Ultra-lightweight native WPF companion runner (84.5 KB).
  • Global Command: overarch available anywhere in Windows terminal.

Core Capabilities

• 7-Stage Epistemic Loop:
  1. Understand: Parse goal and establish epistemic tracking.
  2. Inspect: Discover repository structure and run parallel read-only inspections.
  3. Plan: Structure actionable roadmaps with clear milestones.
  4. Approve: CCHCFAI human control gating and pre-mutation checkpointing.
  5. Execute: Sequential deterministic tool mutations with loop prevention.
  6. Verify: Autonomous verification of modifications against test suites.
  7. Learn: Record lessons learned from self-correction and user feedback.
• CCSS 5.0 Orchestration:
  • /ccss auto: Balanced autonomy for standard feature engineering.
  • /ccss master: Exhaustive planning and checkpoint validation.
  • /ccss god: End-to-end full autonomy for major refactors.
  • /ccss control: Supervised execution requiring explicit human approval.
• CCHCFAI Human Control Guardrails:
  • Tier 0 (Read-Only): File inspection, symbol discovery, and directory listings.
  • Tier 1 (Safe Mutation): Non-destructive local modifications.
  • Tier 2 (State-Mutating): Shell execution and file creation with notification and approval gates.
  • Tier 3 (High-Impact): Mandatory explicit confirmation for deletions or out-of-scope actions.
  • Emergency Stop: Instant halt via Ctrl+C or /halt.
• BYOK (Bring Your Own Key):
  • Supports OpenAI (gpt-4o), Anthropic Claude (claude-3-5-sonnet), Google Gemini (gemini-2.5-flash), OpenRouter (openrouter/auto), and local/custom OpenAI-compatible endpoints.
• Ponytail Senior Dev Minimalism:
  • Zero third-party runtime dependencies. Built strictly on standard Node.js built-ins (node:fs/promises, node:child_process, node:readline/promises, node:util.styleText, node:test) and the native Windows C# compiler (csc.exe).

Installation & Setup

Option 1: Custom Windows Installer (GUI)

Run dist-desktop/Overarch-Setup.exe to install Overarch CLI, create desktop and Start Menu shortcuts, and register overarch in your system PATH.

Option 2: Run via Node.js

cd overarch
npm install
npm run build
npm start

Option 3: Global Terminal Command

overarch

CLI Commands

| Command | Description | |---|---| | overarch | Launch interactive terminal agent session | | overarch memory show | Display project memory and learned episodic lessons | | overarch memory search <query> | Search memory for specific patterns, conventions, or lessons | | overarch memory forget <id> | Remove a specific learned memory by ID | | overarch learn "<lesson>" | Teach Overarch an engineering insight or rule | | overarch companion start | Launch the floating Petdex desktop companion | | overarch companion status | Inspect companion status, active pet, and event bridge | | overarch companion pets | List all discovered Petdex pets | | overarch companion select <slug> | Switch active companion pet | | overarch companion install <slug> | Install a pet from Petdex library via official CLI | | overarch setup | Run interactive onboarding wizard (providers, keys, models) | | overarch doctor | Health check: Node environment, Git status, provider keys | | overarch init | Initialize .overarch/ directory with project config and instructions | | overarch status | Display workspace status card (project, model, git branch) | | overarch models | List available models across supported providers | | overarch config | Inspect active hierarchical configuration | | overarch sessions | List saved sessions with timestamps and message summaries | | overarch resume [id] | Resume previous session or specific session by prefix |

In-Session Slash Commands

Inside the interactive REPL:

PERSISTENT LEARNING & MEMORY
  /memory [show]      Display project memory & learned episodic lessons
  /memory search <q>  Search lessons, conventions, and architectural decisions
  /memory forget <id> Remove a specific learned memory
  /learn "<lesson>"   Record a new engineering insight into memory

SESSION
  /status             Display diagnostic dashboard card
  /new                Start a fresh session in current project
  /resume [id]        Resume past session by ID or prefix
  /sessions           List saved sessions with summaries
  /clear              Clear conversation history
  /exit, /quit        Save session and exit cleanly

PROJECT & REPOSITORY
  /project [dir]      Inspect current workspace or switch directory
  /project recent     List recently accessed projects
  /init               Initialize .overarch subsystem for this project
  /context            Deep inspection of files, stack, and tokens
  /reload             Re-scan workspace context and instructions
  /checkpoint [name]  Create an instant git/snapshot checkpoint
  /checkpoints        List all saved checkpoints
  /rollback [id]      Revert repository to a previous checkpoint
  /diff, /changes     Inspect uncommitted git working tree changes

AI & AGENT
  /model [name]       List available models or switch active model
  /plan [on|off]      Toggle Plan Mode (roadmap before changes)
  /retry              Re-execute last prompt with updated approach
  /ponytail [level]   Set Ponytail minimalism: lite | full | ultra
  /ccss [mode]        Set CCSS mission orchestration: auto | master | god | control
  /cchcfai [action]   Human control layer: gate | audit | halt | status
  /companion [action] Floating desktop companion: start | stop | status | pets | select
  /petdex [action]    Alias for /companion (Petdex integration)
  /tools              List available tools, permission tiers, and MCP
  /abort, /halt       Emergency stop current agent operation

Architecture

Overarch CLI Architecture
├── bin/overarch.ts            # CLI entry point, subcommands & argument dispatch
├── src/cli/
│    ├── repl.ts               # Terminal REPL, Claude-like spinner & command routing
│    ├── ui.ts                 # Pixel logo, ANSI diff formatting & thinking adjectives
│    └── commands/             # Subcommands (memory, doctor, setup, companion, status, etc.)
├── src/companion/             # Petdex Desktop Companion Integration
│    ├── petdex_adapter.ts     # Multi-directory pet discovery & spritesheet mapping
│    ├── petdex_bridge.ts      # HTTP/SSE event server & desktop process manager
│    └── types.ts              # Petdex schemas & AgentState animation row mappings
├── src/learning/              # Persistent Learning Architecture
│    ├── memory_manager.ts     # Disk persistence, selective retrieval & token bounding
│    └── types.ts              # EpisodicLesson, ProjectMemory, UserMemory schemas
├── src/agent/
│    ├── runtime.ts            # 7-stage epistemic agent pipeline & self-correction
│    ├── planner.ts            # CCSS modes (auto, master, god, control) & roadmaps
│    ├── manifest.ts           # AST symbol extractor & repository intelligence
│    ├── context.ts            # Workspace discovery & instruction loader
│    └── context_compressor.ts # Token-efficient context compression
├── src/security/
│    ├── permissions.ts        # CCHCFAI Tier 0-3 permission checker
│    └── guardrails.ts         # Path traversal defense & emergency stop
├── src/tools/
│    ├── filesystem.ts         # Precision slice reader, diff-aware writer & patcher
│    ├── git.ts                # Git operations & branch inspection
│    ├── checkpoint.ts         # Snapshot & rollback engine
│    ├── symbols.ts            # Symbol search & reference tracking
│    └── registry.ts           # Tool registry & OpenAI tool-calling schema export
├── src/desktop/
│    ├── launcher.cs           # Native Windows console launcher (< 75KB)
│    ├── companion.cs          # Native WPF floating desktop companion (84.5 KB)
│    └── installer.cs          # Custom WinForms GUI installer (100 KB)
└── src/providers/
     ├── factory.ts            # BYOK provider factory (OpenRouter, Anthropic, OpenAI, Gemini)
     └── validator.ts          # OpenRouter tool_call_id healing & pre-flight integrity

Testing & Verification

Run the full automated test suite:

npm test

Runs 93 automated tests across 24 suites with 100% pass rate using Node.js's built-in node:test runner.

Credits

2026 Made By Yatharth Roy, From The Thursday AI Company of New Delhi