From 5b942ebdfdbd0bb0201c775830a2c8ab64991923 Mon Sep 17 00:00:00 2001 From: Bryan Helmkamp Date: Tue, 10 Mar 2026 15:12:43 -0400 Subject: [PATCH] Rewrite README to lead with pain statement and priority features Replace feature tables with a focused bulleted list highlighting deterministic graphs, human-in-the-loop, multi-model routing, cloud sandboxes, SSH/preview, git checkpointing, retros, API, single binary, and open source. Merge the stylesheet example into the workflow example for one cohesive story. Remove TOC, node types table, supported models section, and outdated access warning. Co-Authored-By: Claude Opus 4.6 (1M context) --- README.md | 102 ++++++++++++------------------------------------------ 1 file changed, 22 insertions(+), 80 deletions(-) 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 ---