◆ OVERARCH 1.3.0

The Agentic OS for Autonomous Software Engineering.

npm install -g overarch

Overarch is an autonomous AI software engineering operating system built for real-world software development. Rather than treating code generation as isolated text predictions, Overarch operates across four architectural layers: Backbone (11-stage loop + modular skills), Memory & Knowledge (Obsidian vault integration + provenance-tracked note retrieval), Tooling (Model Context Protocol + native tools), and Distribution (portable packages with automated secret redaction).

$ overarch -a "Diagnose failing unit tests, fix root causes, and verify the test suite passes"

What's New in Overarch 1.3.0 "Agentic OS"

Overarch v1.3.0 builds the underlying operating system for agentic work:

1. Autonomous Loop & Self-Repair Engine: 11-stage state machine (observe → understand → retrieve → select_skills → plan → execute → verify → reflect → repair → learn → complete). When verification or tool execution fails, Overarch initiates a non-terminal self-repair cycle with root-cause diagnosis, alternative formulations, and re-verification before completion.
2. First-Class Modular Skill Architecture (/skills): Skills defined with YAML metadata, execution milestones, tool constraints, and CCHCFAI safety validators. Includes on-demand metadata indexing that keeps context lean.
3. Full MCP Subsystem (Model Context Protocol, /mcp): Native support for MCP servers (process, HTTP, SSE, and builtin adapters), tool schemas, dynamic resources (overarch://...), and prompt templates with timeout enforcement and secret redaction.
4. Knowledge Engine & Obsidian Integration (/knowledge, /vault): Local knowledge vault (.overarch/knowledge/) and external Obsidian vault connector. Parses YAML frontmatter, tags, headings, and internal [[wikilinks]], performing semantic relevance searches and citing provenance in agent decisions.
5. Durable State & Crash Recovery (/state): Persists loop iteration snapshots to .overarch/state/active_state.json. Evaluates safe resume after unexpected interruptions while strictly guaranteeing that unconfirmed destructive actions are NEVER auto-resumed.
6. Dedicated Context Engine (/context breakdown): Assembles rich multi-layer agent context across system base, instructions, repository manifest, memory, knowledge, active skills, and MCP resources with deterministic token budgeting.
7. Autonomous Workflows (/workflows): Multi-step automated jobs (like audit and release-check) with step dependencies, execution progress, and workflow-level CCHCFAI risk aggregation.
8. Configurable Agent Profiles (/profile): Tailored agent personas (builder, reviewer, researcher, release-engineer, debugger) with custom prompt modifiers, recommended tools, and maximum risk tiers.
9. Portable Agent Packages (/package): Export and import shareable skill and workflow packages with automated regex secret redaction ensuring zero leakage of API keys, tokens, or credentials.

Installation & Package Managers

Prerequisites: Node.js >= 20.0.0

# npm
npm install -g overarch

# pnpm
pnpm add -g overarch

# yarn
yarn global add overarch

# bun
bun add -g overarch

# Zero-install runner
npx overarch

Quickstart

# Initialize project workspace (.overarch/ directory)
overarch init

# Run onboarding setup (choose provider, model, theme accent)
overarch setup

# Start interactive agent session
overarch

# Start in autonomous mode (auto-approves routine dev ops)
overarch --auto

# Run a one-off headless autonomous task
overarch -a "Build the project and fix any TypeScript compiler errors"

# Run non-destructive code review
overarch review

# Run environment and backend diagnostics
overarch doctor

Provider Management Commands (v1.1.0)

Manage providers, endpoints, and credentials directly inside the CLI:

# List all registered and detected providers
overarch provider list

# Show the active provider and its endpoint
overarch provider active

# Switch active provider instantly
overarch provider switch ollama
overarch provider switch deepseek
overarch provider switch openai

# Test network and model connectivity (with latency check)
overarch provider test
overarch provider test ollama
overarch provider test anthropic

# Interactively configure a new API or local endpoint
overarch provider add

# Reset provider configuration to default
overarch provider reset

# Export configuration (zero secrets exposed)
overarch provider export config-clean.json

# Import configuration
overarch provider import config-clean.json

Autonomy & Permission Modes

Configure permissions via overarch --permissions <mode> or /permissions <mode>:

| Mode | Description | |---|---| | auto / autonomous | Default experience. Routine file operations and safe build/test commands execute autonomously. Approval is only requested for deletions, credential files, or external pushes. | | approval | Prompts for confirmation before executing state-mutating actions (file writes, commands). | | restricted | Safe read-only mode. All file mutations, deletions, and shell executions are blocked. | | plan | Analyzes tasks and outputs structured implementation plans without modifying code. |

In-Session Slash Commands

| Command | Action | |---|---| | /skills | List, show, create, and validate modular agent skills | | /mcp | Inspect Model Context Protocol servers, tools, resources, and prompts | | /knowledge | Search engineering notes, sync vaults, and connect Obsidian vaults | | /state | Inspect durable execution snapshots and safe crash recovery | | /workflows | Execute multi-step autonomous workflows with CCHCFAI safety gates | | /profile | Switch agent profile (builder, reviewer, researcher, release-engineer, debugger) | | /package | Export and import shareable packages with automated secret redaction | | /provider | Switch, test, and manage providers in-session | | /models | View available and discovered models | | /status | View active model, token usage, and session health | | /context | Inspect discovered repository files, multi-layer breakdown, and token budget | | /plan | Task roadmap formulation and milestone decomposition | | /checkpoint | View recent shadow backup snapshots | | /undo | Roll back the last file modification made by the agent | | /clear | Clear message history while keeping repository context | | /new | Start a fresh session | | /sessions | List and resume previous sessions | | /reload | Reload instructions and project memory from disk | | /doctor | Run comprehensive health and backend checks | | /help | View categorized command cheatsheet | | /exit | Save session state and exit cleanly |

Security: CCHCFAI Guardrails

Overarch enforces the Creative Customs Human Control for AI (CCHCFAI) safety protocol:

1. State Isolation: Private reasoning, plan proposals, and disk mutations remain strictly separated.
2. Action Impact Tiers:
   • Tier 0 (Read-Only): File reads, directory listing, symbol queries (auto-approved).
   • Tier 1 (Safe Local Mutation): File creation, code edits with automatic shadow checkpoints (auto-approved in auto mode).
   • Tier 2 (External / State-Mutating): Package installations, build tools (notified in terminal).
   • Tier 3 (Destructive): File deletions, destructive git operations (mandatory human confirmation gate).
3. Emergency Stop: Type /stop, /halt, cancel, or press Ctrl+C to halt the agent immediately.

Links

• Repository: https://github.com/yatharth-real/Overarch
• NPM Package: https://www.npmjs.com/package/overarch

License

MIT © 2026 Yatharth Roy & The Overarch Contributors.