diff --git a/README.md b/README.md index ececcffd0..c378d76f2 100644 --- a/README.md +++ b/README.md @@ -4,52 +4,25 @@ ## The software factory for small teams of expert engineers -Arc replaces the prompt-wait-review loop with version-controlled workflow graphs that orchestrate AI agents, shell commands, and human decisions into repeatable, long-horizon coding processes. - -Define workflows in Graphviz DOT, route tasks to the right model with CSS-like stylesheets, and let the engine handle orchestration, parallelism, checkpointing, and verification -- all from a single Rust binary. +AI coding agents are powerful but unpredictable. You either babysit every step or review a 50-file diff you don't trust. Arc gives you a middle path: define the process as a graph, let agents execute it, and intervene only where it matters. [![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE.md) [![docs](https://img.shields.io/badge/docs-arc.dev-357F9E)](https://arc.dev) --- -## Table of Contents - -- [Key Features](#key-features) -- [Quick Start](#quick-start) -- [Example Workflow](#example-workflow) -- [Supported Models](#supported-models) -- [System Requirements](#system-requirements) -- [Help or Feedback](#help-or-feedback) -- [Contributing](#contributing) -- [License](#license) - ---- - ## Key Features -### What Arc Does - -| | Feature | Description | -| --- | -------------------------- | ------------------------------------------------------------------------------------------ | -| :robot: | Multi-model orchestration | Route tasks to the right model per node -- cheap for boilerplate, frontier for hard reasoning | -| :diamond_shape_with_a_dot_inside: | Declarative workflows | Define pipelines in Graphviz DOT -- diffable, reviewable, composable | -| :raised_hand: | Human-in-the-loop | Approval gates, interviews, and real-time steering let you intervene at the right moments | -| :arrows_counterclockwise: | Checkpoint and resume | Git-native checkpointing after every stage -- inspect, revert, or fork from any point | -| :shield: | Adaptive verification | Combine LLM-as-judge, test suites, and human review into quality gates | -| :bar_chart: | Full observability | Every tool call, agent turn, and decision point captured in a unified event stream | - -### How Arc Does It - -| | Feature | Description | -| --- | ----------------------- | ---------------------------------------------------------------------------------------- | -| :art: | Model stylesheets | CSS-like selectors (`*`, `.class`, `#id`) assign models, providers, and reasoning effort | -| :deciduous_tree: | Git-native checkpoints | Every stage commits to a branch -- resume interrupted runs exactly where they left off | -| :package: | Sandbox isolation | Run agent tools in local, Docker, Daytona cloud VMs, or exe.dev ephemeral VMs | -| :electric_plug: | MCP integration | Extend agents with any Model Context Protocol server (Playwright, databases, APIs) | -| :repeat: | Loops and fan-out | Implement-test-fix cycles, parallel code reviews, and ensemble multi-provider patterns | -| :crab: | Written in Rust | Single compiled binary with minimal dependencies -- no Python runtime, no npm install | -| :gear: | CLI and API modes | `arc run` for local dev, `arc serve` for production with a React web UI | +- **Deterministic workflow graphs** -- Define pipelines in Graphviz DOT with branching, loops, parallelism, and human gates. Diffable, reviewable, version-controlled. +- **Human-in-the-loop** -- Approval gates pause for human decisions. Steer running agents mid-turn. Interview steps collect structured input. You stay in control without babysitting. +- **Multi-model routing** -- Route each node to the right model and provider with CSS-like stylesheets. Cheap models for boilerplate, frontier models for hard reasoning, with automatic provider fallback. +- **Cloud sandboxes** -- Run agents in isolated Daytona cloud VMs with snapshot-based setup, network controls, and automatic cleanup. +- **SSH access and preview links** -- Shell into running sandboxes with `arc ssh` and expose ports with `arc preview` for live debugging while workflows run. +- **Git checkpointing** -- Every stage commits to a branch. Inspect changes, revert mistakes, or resume interrupted runs exactly where they left off. +- **Automatic retros** -- Each run generates a retrospective with cost, duration, files touched, and an LLM-written narrative rating smoothness and flagging friction points. +- **Comprehensive API** -- `arc serve` exposes a full REST API with SSE event streaming and a React web UI. Run workflows programmatically, build integrations, or operate Arc as a service. +- **Single binary, no runtime** -- One compiled Rust executable with zero dependencies. No Python, no Node, no Docker required to get started. +- **Open source (MIT)** -- Full source code, no vendor lock-in. Self-host, fork, or extend to fit your workflow. Read the full [documentation](https://arc.dev) for details. @@ -57,9 +30,6 @@ Read the full [documentation](https://arc.dev) for details. ## Quick Start -> [!WARNING] -> Arc is in private research preview. Contact [bryan@qlty.sh](mailto:bryan@qlty.sh) if you're interested in trying it. - ### Install Download the latest release for your platform: @@ -117,15 +87,21 @@ A plan-approve-implement workflow where a human reviews the plan before the agen ```dot digraph PlanImplement { - graph [goal="Plan, approve, implement, and simplify a change"] + graph [ + goal="Plan, approve, implement, and simplify a change" + model_stylesheet=" + * { llm_model: claude-haiku-4-5; reasoning_effort: low; } + .coding { llm_model: claude-sonnet-4-5; reasoning_effort: high; } + " + ] start [shape=Mdiamond, label="Start"] exit [shape=Msquare, label="Exit"] plan [label="Plan", prompt="Analyze the goal and codebase. Write a step-by-step plan.", reasoning_effort="high"] approve [shape=hexagon, label="Approve Plan"] - implement [label="Implement", prompt="Read plan.md and implement every step."] - simplify [label="Simplify", prompt="Review the changes for clarity and correctness."] + implement [label="Implement", class="coding", prompt="Read plan.md and implement every step."] + simplify [label="Simplify", class="coding", prompt="Review the changes for clarity and correctness."] start -> plan -> approve approve -> implement [label="[A] Approve"] @@ -134,41 +110,7 @@ digraph PlanImplement { } ``` -### Node types at a glance - -| Shape | Type | What it does | -| ---------------- | ----------- | ------------------------------------------------ | -| `Mdiamond` | Start | Workflow entry point | -| `Msquare` | Exit | Workflow terminal | -| `box` (default) | Agent | Multi-turn LLM with tool access | -| `tab` | Prompt | Single LLM call, no tools | -| `parallelogram` | Command | Runs a shell script | -| `hexagon` | Human gate | Pauses for human input | -| `diamond` | Conditional | Routes based on conditions | -| `component` | Parallel | Fans out to concurrent branches | -| `tripleoctagon` | Merge | Collects parallel branch results | - -### Multi-model routing with stylesheets - -```dot -graph [ - model_stylesheet=" - * { llm_model: claude-haiku-4-5; reasoning_effort: low; } - .coding { llm_model: claude-sonnet-4-5; reasoning_effort: high; } - #review { llm_model: gemini-3.1-pro-preview; llm_provider: gemini; } - " -] -``` - -Selectors follow CSS specificity: `*` (0) < `shape` (1) < `.class` (2) < `#id` (3). - ---- - -## Supported Models - -Arc supports models from Anthropic, OpenAI, Gemini, Kimi, Zai, MiniMax, and Inception. Route tasks to the right model per node and configure provider fallback chains per-run. - -Run `arc model list` locally or see the [Models documentation](https://arc.dev/core-concepts/models) for the full catalog. +Agents run as multi-turn LLM sessions with tool access. Human gates (`hexagon`) pause for approval. The stylesheet routes planning to a cheap model and coding to a frontier model. See the [DOT language reference](https://arc.dev/reference/dot-language) for the full syntax. --- @@ -186,7 +128,7 @@ Run `arc model list` locally or see the [Models documentation](https://arc.dev/c - Read the [documentation](https://arc.dev) - [Bug reports](https://github.com/brynary/arc/issues) via GitHub Issues - [Feature requests](https://github.com/brynary/arc/issues) via GitHub Issues -- Email [bryan@qlty.sh](mailto:bryan@qlty.sh) for access or questions +- Email [bryan@qlty.sh](mailto:bryan@qlty.sh) for questions ---