Raddus Graph

Raddus Graph is a local web app for designing and running CLI-backed agent graphs. It lets you define agent specs, result IDs, play nodes, and expression cards, then run graph sessions through local Codex or Claude CLI processes.

Features

• Create local agent specs from a model, name, and system prompt.
• Generate a new project graph from a prompt through a local Codex or Claude CLI agent.
• Review the current graph with a local agent, inspect proposed change summaries, and apply the rebuilt graph after confirmation.
• Build graph sessions from play nodes, agent nodes, and expression cards.
• Use the permanent Any card to apply an expression route to every agent in a graph.
• See transparent parent graph cues when another runnable graph card can execute the current graph.
• Route expressions to play cards to continue a loop in a fresh graph session with the same launch parameters.
• Use the top-center approval button when any agent emits ask-for-approval.
• Define graph-scoped result IDs and route terminal outcomes through expression cards.
• Persist graph data, agent specs, graph sessions, agent sessions, status records, retained worktrees, and PR mappings under .raddus-graph/.
• Run Codex CLI or Claude CLI sessions from the local Node.js server based on the selected model.
• Select a GitHub repository and branch from the authenticated local gh user, or run with no repository.
• Retain one worktree per graph session and publish file changes to one session branch and pull request.

Requirements

• Node.js 20.19 or newer, or Node.js 22.12 or newer.
• npm.
• Codex CLI for models mapped to the Codex runner.
• Claude CLI for models mapped to the Claude runner.
• GitHub CLI (gh) authenticated with a GitHub account for repository and pull request workflows.

If gh is unavailable or unauthenticated, Raddus Graph still runs and the play-card repository selector only offers None.

Setup

Install the package globally:

npm i -g @raddus/graph

Start Raddus Graph:

raddus-graph

The server prints the local URL when it starts, for example:

Raddus Graph listening at http://127.0.0.1:5174

It also opens that URL in your default browser. To start the server without opening a browser:

raddus-graph --no-open

The old raddus-canvas binary remains as a compatibility alias for now.

Local Development

Clone the repository and install dependencies:

npm install

Run the app in development mode:

npm run dev

Build the production bundle:

npm run build

Local Data

By default, Raddus Graph stores local runtime data in ~/.raddus-graph/. Override this with:

RADDUS_GRAPH_DIR=/path/to/.raddus-graph raddus-graph

The store contains:

• state.json: graph design data, agent specs, result definitions, graph session metadata, agent sessions, status timelines, terminal outcomes, and PR mappings.
• sessions/<graph-session-id>/worktree: the retained workspace for a graph session.

Runtime Model

Running a play node creates a graph session id. Each agent node execution within that graph session creates its own agent session id. The server snapshots the current graph, provisions a retained session worktree, and executes one graph path at a time.

Each agent session records the node and agent spec it ran, the full assembled prompt, stdout/stderr, status timeline, terminal outcome, and the route that led into it:

• previous agent session id
• incoming expression card id
• incoming edge ids
• incoming result id

Agent prompts are assembled as structured Markdown with:

• repository and branch
• compact behavior instructions
• the local status callback contract
• recent prior agent handoff details under History
• the play-node prompt or review response as the final User Context section

Agent sessions append progress and terminal outcome JSON to the local status file named by RADDUS_GRAPH_STATUS_FILE. The file uses one compact JSON object per line and is deleted by the server before workspace changes are published.

Agent sessions may also post live progress JSON to:

POST /api/graph/sessions/:graphSessionId/agent-sessions/:agentSessionId/status

The HTTP callback is optional because the agent sandbox may not be able to reach 127.0.0.1.

Graph sessions can be removed with:

DELETE /api/graph/sessions/:graphSessionId

Removing a graph session stops active child processes first and deletes the retained session workspace. Completed, failed, and stopped graph sessions can be continued from the Sessions window. Continuation reuses the retained workspace, tries the current project graph first, and falls back to the stored session snapshot.

Expression cards route only after terminal outcomes. completed routes by a valid emitted result ID. Unknown, invalid, or unbranched outcomes route through reserved default. Expressions can route to agents, graph cards, or play cards. A play-card route starts a new graph session with the same launch prompt, repository, and branch. Play cards can start agents or graph cards directly; after that, graph cards route through expressions and return the result from the last agent node inside that graph. Any agent can emit ask-for-approval to pause the graph and show the top-center approval button. stopped ends without routing.

The canvas can follow a graph session. In follow mode, the active agent node is highlighted, the previous node and incoming expression path are shown less strongly, and earlier visited nodes/routes keep subtle markers. Selecting a graph session from the Sessions window switches the canvas to that session's execution state.

If a repository-backed session changes files, Raddus Graph creates one session branch and pull request after changes first need publishing. Later modifying agents in the same graph session push to the same branch and pull request.

Architecture

Raddus Graph has two main parts:

• bin/raddus-graph.mjs: the CLI entrypoint used by the published commands.
• server/: local Node.js runtime modules that serve the app, manage graph persistence, launch CLI runners, discover GitHub repositories, and publish session pull requests.
• server.mjs: a small compatibility launcher for running the server from the repository root.
• src/main.tsx: the React mount entrypoint.
• src/App.tsx: the Raddus Graph frontend controller.
• src/api/RaddusGraphApi.ts: the frontend API client for /api/graph/*.
• docs/adr/: architecture decision records.

At runtime:

1. The user starts the local Node.js server.
2. The server initializes .raddus-graph/ and serves the frontend over localhost.
3. The frontend loads graph state through /api/graph/state.
4. The server lists GitHub repositories through gh when available.
5. A play node creates a graph session.
6. The server runs CLI agents sequentially, receives node status callbacks, routes expression cards, and persists outcomes.

Publishing

Use npm to publish a new version of @raddus/graph:

npm run publish:patch

Use npm run publish:minor or npm run publish:major when publishing a larger version bump.