Skip to content

README.md

Latest commit

 

History

History
72 lines (54 loc) · 3.04 KB

README.md

File metadata and controls

72 lines (54 loc) · 3.04 KB
Raw

graph-max

Pre-release: this repository is building graph-max@0.1.0; the public package and the commands below are planned, not yet released.

graph-max is a colored, CLI-first graph runner for developers who use Codex CLI. Define an agent graph in JSON or YAML instead of writing orchestration code. v0.1 uses Codex CLI as its only backend; MCP is deliberately later.

Snapshot-isolated Context

There is no shared mutable graph context. A successful node commits one immutable snapshot. Parallel reviewers receive separate serialized inputs that reference the same predecessor snapshot; neither can mutate the other’s prompt, object, or Codex session. By default, a node gets the original run input and its immediate predecessors—not every ancestor.

Local SQLite Run Store

Runs, activations, events, snapshot lineage, and safe artifact metadata live in one SQLite database per canonical project outside the Codex workspace-write root. Small payloads are inline; larger outputs are content-addressed blobs beside the database. Traces exclude prompts, environment values, reasoning, credentials, and full tool transcripts.

Current implementation status

The local SQLite store is implemented and tested: it uses Bun's built-in bun:sqlite, WAL and foreign keys, content-addressed blob payloads, immutable activation commits, safe inspection metadata, frozen input selections, and deterministic join hashes. GRAPH_MAX_STATE_DIR provides a test/CI override; the normal location is outside the canonical workspace. The live Codex compatibility spike is still pending, so no Codex executor, scheduler, or public run behavior is claimed yet.

Planned command journey

graph-max init --template review-and-synthesize
graph-max validate graph-max.yaml
graph-max run graph-max.yaml --input "Review this repository"
graph-max inspect <run-id>
graph-max inspect <run-id> --node correctness-review

The first template illustrates a useful graph without custom orchestration:

scout -> correctness-review ─┐
      -> maintainability-review -> reviews (deterministic join) -> synthesize -> decision-gate

doctor, template list, template show, init, validate, run, inspect, --help, and --version are the GM-01 command surface. Human output will color only TTYs and honor NO_COLOR/--no-color; --json will emit stable JSONL.

Graph vs. loop

Use graph-max for finite, inspectable work with declared dataflow, fan-out, joins, and locally validated gate decisions. Do not use it for feedback loops, retries, or persistent sessions in v0.1—those are explicitly deferred rather than hidden behind an implicit control loop.

Safety model

The graph default is workspace-write; individual nodes may narrow to read-only. Graph configuration cannot store danger-full-access. Gate conditions use RFC 6901 JSON Pointer and fixed operators, never arbitrary code.

See the engineering research, architecture decisions, and the development checklist.