ShellForge

Governed AI agent runtime -- single Go binary, local or cloud models.

Architecture

flowchart TD
    subgraph "Entry Points"
        Chat[shellforge chat]
        Agent[shellforge agent]
        Ralph[shellforge ralph]
        Run[shellforge run driver]
        Serve[shellforge serve]
    end

    Chat & Agent & Ralph --> Loop[Agent Loop]
    Run --> Driver[CLI Driver Subprocess]
    Serve --> Scheduler[Scheduler + Queue]
    Scheduler --> Loop

    Loop --> Intent[Intent Parser]
    Intent -->|"any format: JSON, XML, bare"| Normalizer[Normalizer]
    Normalizer -->|Canonical Action| Gov

    Loop --> ProviderPath[Native Tool-Use Path]
    ProviderPath --> Gov

    subgraph "Governance Layer"
        Gov[governance.Engine] -->|evaluate| Policy[agentguard.yaml]
        Policy -->|deny| Correction[Correction Engine]
        Policy -->|allow| Tools
    end

    Correction -->|structured feedback| Loop

    subgraph "Tool Execution"
        Tools[8 Built-in Tools]
        Tools --> RFile[read_file]
        Tools --> WFile[write_file]
        Tools --> Edit[edit_file]
        Tools --> Shell[run_shell]
        Tools --> Glob[glob]
        Tools --> Grep[grep]
        Tools --> LS[list_directory]
        Tools --> Search[search_files]
    end

    subgraph "LLM Providers"
        Loop --> Ollama[Ollama - local]
        Loop --> Anthropic[Anthropic API]
    end

    Loop --> Drift[Drift Detector]
    Drift -->|score below threshold| Kill[Kill / Steer]

Getting Started

Prerequisites

Go 1.18+ (for building from source)
Ollama for local model inference, or an Anthropic API key for cloud

Install

From source:

git clone https://github.com/chitinhq/shellforge.git
cd shellforge
go build -o shellforge ./cmd/shellforge/

Or via Homebrew:

brew tap chitinhq/tap
brew install shellforge

Quick Start

# Pull a model and start Ollama
ollama pull qwen3:8b
ollama serve

# Initialize governance in your project
cd ~/your-project
shellforge setup

# Interactive pair-programming
shellforge chat

# One-shot agent task
shellforge agent "describe what this project does"

# Multi-task loop with validation
shellforge ralph tasks.json --validate "go test ./..."

CLI Commands

| Command | Description | |---------|-------------| | shellforge chat | Interactive REPL with persistent conversation history | | shellforge agent "prompt" | One-shot governed agent execution | | shellforge ralph tasks.json | Stateless-iterative multi-task loop (pick, implement, validate, commit) | | shellforge run <driver> "prompt" | Run a governed CLI driver (claude, copilot, codex, gemini, openclaw, nemoclaw) | | shellforge serve agents.yaml | Daemon mode -- memory-aware agent scheduling | | shellforge setup | Create governance config and verify stack | | shellforge status | Ecosystem health check | | shellforge qa [dir] | QA analysis with tool use | | shellforge report [repo] | Status report from git + logs | | shellforge scan [dir] | DefenseClaw supply chain scan | | shellforge canon "cmd" | Parse shell command into canonical JSON |

Provider Flags

shellforge chat --provider anthropic          # Cloud model via Anthropic API
shellforge chat --model qwen3:14b             # Specific Ollama model
shellforge agent --thinking-budget 8000 "prompt"  # Extended thinking (Sonnet/Opus)

Governance

Every tool call passes through the governance engine before execution. Policies are defined in agentguard.yaml:

mode: enforce   # enforce | monitor

policies:
  - name: no-force-push
    action: deny
    match:
      command: "git push"
      args_contain: ["--force"]

  - name: no-destructive-rm
    action: deny
    match:
      command: "rm"
      args_contain: ["-rf"]

When a tool call is denied, the correction engine feeds structured feedback back to the model so it can self-correct rather than simply fail.

Key Internals

| Package | Purpose | |---------|---------| | internal/agent | Core agent loop with tool calling, drift detection, context compaction | | internal/governance | Policy engine -- evaluates every action against agentguard.yaml | | internal/correction | Escalating feedback for denied actions (retry budget + structured hints) | | internal/intent | Format-agnostic intent parser (JSON, XML, bare JSON, OpenAI function_call) | | internal/normalizer | Converts any tool call into a Canonical Action Representation | | internal/llm | Provider interface with Anthropic (prompt caching, native tool-use) and Ollama backends | | internal/tools | 8 governed tools: read, write, edit, glob, grep, shell, list, search | | internal/ralph | Stateless-iterative task loop with validation and auto-commit | | internal/repl | Interactive REPL with color output, shell escapes, signal handling | | internal/scheduler | Memory-aware agent queue for daemon mode | | internal/orchestrator | Sub-agent orchestration with context compression |

Development

go build ./cmd/shellforge/
go test ./...
golangci-lint run

License

MIT

Shellforge

Install / Use

README