Manul — Agentic Coding Assistant

Overview

Manul is an agentic coding assistant that runs entirely in the terminal — a from-scratch take on the “AI pair-programmer” pattern, designed to be model-agnostic and local-first. It streams reasoning and live tool output into a React + Ink interface, and drives real work through a sandboxed tool layer rather than just chatting about code.

Architecture

flowchart TB
    subgraph UI["Interfaces"]
        TUI["Terminal UI<br/>React + Ink"]
        VSC["VS Code Extension"]
    end

    subgraph CORE["Agent Core"]
        LOOP["Agent Loop<br/>plan · act · observe"]
        STATE["Session State<br/>history · tokens"]
        IMG["Image Input<br/>path · clipboard"]
    end

    subgraph ROUTER["Provider Router"]
        CLOUD["OpenAI · Anthropic<br/>Azure · Bedrock"]
        LOCAL["Ollama · LM Studio<br/>local · no key"]
    end

    subgraph TOOLS["16-Tool Layer"]
        FILE["Files<br/>read · write · edit"]
        SHELL["Shell · bash"]
        NAV["Navigate<br/>glob · grep · ls · tree"]
        COMP["Comprehend<br/>context · search<br/>diff"]
    end

    TUI --> LOOP
    VSC --> LOOP
    IMG --> LOOP
    LOOP <--> STATE
    LOOP -->|prompt| ROUTER
    ROUTER -->|tokens| LOOP
    LOOP -->|tool calls| TOOLS
    TOOLS --> GUARD["Safety Guardrails<br/>guarded bash<br/>safe writes"]
    GUARD --> WS["Working Tree<br/>files · shell"]
    WS -->|results| LOOP

• Provider abstraction — a single agent loop talks to OpenAI, Anthropic, Azure OpenAI, AWS Bedrock, Ollama, and LM Studio behind one interface. The provider is auto-detected from the model name (gpt-*, claude-*) or set with an explicit prefix (ollama/llama3.2, bedrock/...), so swapping models is a config change, not a code change.
• Tool execution layer — 16 built-in tools (read, write, edit, bash, glob, grep, tree, diff, full-text search, repo-mapping context, and more) give the agent real filesystem and shell capabilities, with uniqueness checks on edits and absolute-path enforcement on writes.
• Code understanding — a context tool builds a repo map via tree-sitter, letting the agent reason about structure instead of reading files blindly.
• Streaming TUI — React + Ink renders streaming responses, live tool output, a thinking indicator with elapsed time + token counter, image attachments (file path or clipboard paste), input history, and mid-run interruption with Esc.

Engineering Decisions

• Local-first by design — Ollama and LM Studio need no API key, so the same agent runs fully offline or against frontier cloud models without changing the workflow.
• Safety guardrails — dangerous shell patterns are blocked and writes are constrained to absolute paths, keeping an autonomous agent from doing damage in a real working tree.
• Two surfaces, one engine — ships as both a CLI and a VS Code extension on top of the same core agent loop.

Highlights

• 6 model providers unified behind one auto-detecting interface
• 16 built-in tools spanning read/write/edit, shell, search, and tree-sitter repo mapping
• Streaming, interruptible terminal UX with token + timing telemetry