# Obversa

> Public documentation for the Obversa packages

- [Documentation](https://obversa.ai/docs/index.md): Durable workflows for agent teams in TypeScript: named roles, evals that decide the next step, and a person's approval where you want one.
- [Installation](https://obversa.ai/docs/get-started/installation.md): Install Obversa and prepare your project to run an agent workflow.
- [First Run](https://obversa.ai/docs/get-started/first-run.md): Have Claude write a function, run its tests, and ask Codex to review it.
- [Workflows](https://obversa.ai/docs/concepts/workflows.md): The shape of the work: steps, reviews and decisions, as a TypeScript file.
- [Feedback Loops](https://obversa.ai/docs/concepts/feedback-loops.md): A check fails a step, the findings travel, and the step runs again, up to a limit.
- [The Record](https://obversa.ai/docs/concepts/record.md): The append-only event log a run writes, and the single source of truth a stopped run carries on from.
- [Running](https://obversa.ai/docs/concepts/running.md): Runs workflows.
- [Where a Workflow Lives](https://obversa.ai/docs/concepts/where-a-workflow-lives.md): Runs from wherever you keep it.
- [Surfaces](https://obversa.ai/docs/concepts/surfaces.md): Review work in a browser. Your choices, edits and comments become feedback for the agent.
- [Memory](https://obversa.ai/docs/concepts/memory.md): Files a step can open again later, behind one small port.
- [Workspace](https://obversa.ai/docs/concepts/workspace.md): A Git worktree per writer, captured and verified, so two writers never collide.
- [Patterns](https://obversa.ai/docs/patterns/index.md): Familiar ways to review, compare, decide, and keep work moving.
- [Get a Second Opinion](https://obversa.ai/docs/patterns/writer-and-reviewer.md): A different model reviews the work and gives the writer notes to act on.
- [Check the Brief Was Met](https://obversa.ai/docs/patterns/check-the-brief.md): A second model checks every requirement in the brief before the reviews run.
- [Ask a Panel](https://obversa.ai/docs/patterns/review-panel.md): Several models review the same work, their reviews become one, and a judge decides each finding.
- [Know When to Stop](https://obversa.ai/docs/patterns/judge-stops-the-loop.md): A judge reads each review note and decides which ones are worth another round.
- [Compare Different Approaches](https://obversa.ai/docs/patterns/tournament.md): Try several approaches, score each with a function, and keep the highest-scoring pass.
- [Automate the Routine Work](https://obversa.ai/docs/patterns/command-kickback.md): A command checks the work and its result decides what runs next.
- [Ask a Person](https://obversa.ai/docs/patterns/approval.md): Pause for a person's answer and keep their decision with the work.
- [Check Before Acting](https://obversa.ai/docs/patterns/safe-change.md): Approve exact file bytes, back up the target, and check what was written.
- [Bring the Team Together](https://obversa.ai/docs/patterns/team-conversation.md): Named team members ask, answer, and keep their conversation in the run.
- [Examples](https://obversa.ai/docs/workflows/index.md): Complete teams you can run on your own work, grouped by field.
- [Feature Delivery](https://obversa.ai/docs/workflows/feature-team.md): A ticket built and tested, checked against every requirement, reviewed by three model families, judged finding by finding, and approved on its exact bytes.
- [Shipping a Reviewed Change Through GitHub](https://obversa.ai/docs/workflows/forge-helper.md): Push the branch, open one pull request, pass a strict gate on the exact head revision, squash the merge.
- [Backlog Grooming, Then a Person Ranks](https://obversa.ai/docs/workflows/backlog-groom-then-rank.md): Raw tickets become stories with acceptance checks, a second model reads them back, and the product owner ranks.
- [A Shape Up Cycle](https://obversa.ai/docs/workflows/product/shape-up-cycle.md): Pitches, a person's bets, and a build inside a fixed time.
- [Market Observations, Then a Person Considers](https://obversa.ai/docs/workflows/markets/market-session-advice.md): Every observation is read the same way. A person decides any action.
- [Invoice Chasing, a Person on Disputes](https://obversa.ai/docs/workflows/finance/invoice-chase.md): The ledger names what is overdue. You see every dispute.
- [Contract Review Against a Playbook](https://obversa.ai/docs/workflows/contract-playbook.md): Every clause mapped to the playbook rule it meets or breaks, redlines checked by a second model, and a lawyer decides what is sent.
- [Outreach Drafted by a Model, Sent by a Person](https://obversa.ai/docs/workflows/sales/draft-then-send.md): A model drafts each note. Nothing is sent without your yes.
- [Support Triage, a Person on the Rest](https://obversa.ai/docs/workflows/support/triage-with-escalation.md): Routine replies can go out. Money, anger, or a bad classification waits.
- [A Shortlist With Verifiable Gates](https://obversa.ai/docs/workflows/hiring/shortlist.md): Rules exclude, two models rank, and you pick the shortlist.
- [Approve the Exact Payload, Not a Story](https://obversa.ai/docs/workflows/ops/approve-the-exact-payload.md): Your yes covers these exact bytes. A changed byte asks again.
- [A Stopped Run Carries On](https://obversa.ai/docs/workflows/ops/handoff-that-resumes.md): A stopped run carries on from its record. Finished work stays finished.
- [Literature Watch, a Person Curates](https://obversa.ai/docs/workflows/research/literature-watch.md): A model summarises each paper. You decide what is kept.
- [A Notes Vault the Person Steers](https://obversa.ai/docs/workflows/knowledge/vault-curator.md): A model proposes a place for each note. You decide what is filed.
- [A Writer, a Strict Grader, a Judge, an Editor](https://obversa.ai/docs/workflows/editorial/writer-grader-cap.md): Another model grades the draft, a judge says when another round stops being worth it, and the editor decides what is published.
- [Translate, Reflect, Glossary, Then You](https://obversa.ai/docs/workflows/translate-reflect.md): One model translates against a glossary, an editor on another model reads it back, and a person decides the nuance.
- [Evals in an Agent Workflow](https://obversa.ai/docs/reviewing/evals.md): Checks that decide the next step: a test, a judge, a panel, a tournament, a score.
- [Callback Gates](https://obversa.ai/docs/reviewing/callback-gates.md): Stop the run for one question a person, an agent or a service must answer, and carry on with the answer.
- [Review Loop](https://obversa.ai/docs/reviewing/review-loop.md): A draft, a done check, independent reviewers and a repair node, as a graph form with a quorum.
- [Decisions Bound to Bytes](https://obversa.ai/docs/reviewing/proof-acceptance.md): Reuse a result or a decision only while every covered byte still matches.
- [A Gate That Shows You the Real Thing](https://obversa.ai/docs/coming-soon/preview-gate.md): Coming soon: A callback gate that hands a person the built thing itself, running and reachable from a phone, with the answer flowing back into the run.
- [Read a Record](https://obversa.ai/docs/recording/read-a-record.md): Prints a run's record as a page a person scans, or as JSON for a page of your own.
- [Events and Artifacts](https://obversa.ai/docs/recording/events-and-artifacts.md): Append small events, store large bytes beside them, and reopen the same state.
- [Safe Node Attempts](https://obversa.ai/docs/recording/node-attempts.md): Run one bounded engine turn and record what was asked, what ran, what came back and what it cost.
- [Supervised Local Runs](https://obversa.ai/docs/driving/runner.md): If the worker dies, a new one reads the record and a finished step does not run again. Engines are checked before the first step.
- [Run One Step on Another Machine](https://obversa.ai/docs/driving/remote-nodes.md): Coming soon: One step of a run executes on a remote machine while the runtime and the record stay on yours, and the change comes back as a commit or a patch.
- [Fast and Deliberate, Side by Side](https://obversa.ai/docs/coming-soon/fast-and-deliberate.md): Coming soon: A fast typed decision runs first, and the work goes to a deliberate seat only when its confidence is under the gate or the decision asks for it.
- [Supervision While a Step Runs](https://obversa.ai/docs/coming-soon/supervision.md): Coming soon: The attempt's own events feed a fast decision model on a debounce, and the run carries on, stops and retries, or puts the step to a person.
- [An Observation Port on Every Workflow](https://obversa.ai/docs/coming-soon/observation-port.md): Coming soon: a stream of a run's events and a published shape for its state.
- [Watch a Run in the Browser](https://obversa.ai/docs/driving/monitor.md): A run serves its own page on a local port: each step's state, the findings, the questions waiting, and the tail of the record.
- [Obversa in cmux](https://obversa.ai/docs/hosts/cmux.md): One Command Palette entry and five scripts: the right editor on the right worktrees, and local pages in splits beside the terminal.
- [Review a Diff](https://obversa.ai/docs/hosts/review.md): obversa-review opens a git diff in a browser pane beside the terminal and returns the comments as structured output.
- [Your Own Workflow Shape](https://obversa.ai/docs/graphs/contract.md): Define, validate and inspect a pure graph type the runtime doesn't ship.
- [Built-in Pipeline](https://obversa.ai/docs/graphs/pipeline.md): Run ordered stages through the stored graph executor with the dag form that ships.
- [Plan Admission](https://obversa.ai/docs/graphs/plan-admission.md): Bind a graph description to a host's admission record and freeze what the run may use.
- [Graph Executor](https://obversa.ai/docs/graphs/executor.md): Run a stored graph one recorded decision at a time, and resume it from the exact record it stopped on.
- [Memory Port](https://obversa.ai/docs/memory/index.md): One command contract for reading and writing memory files, whatever stores them.
- [Memory Adapters](https://obversa.ai/docs/memory/adapters.md): Keep memory in one process, in private Git references, or in a read-only Markdown corpus.
- [Memory Mechanics](https://obversa.ai/docs/memory/mechanics.md): Ground, curate and consolidate memory through functions you supply, over any adapter.
- [Workspace Contract](https://obversa.ai/docs/workspace/contract.md): Capture, verify, lease and fork one Git repository through the public contract.
- [Workspace Example](https://obversa.ai/docs/workspace/example.md): Capture, verify, lease and fork a temporary Git repository, then read the child back.
- [Compare agent workflows](https://obversa.ai/docs/compare/index.md): Compare how Obversa, Conductor, Raven, LangGraph, Mastra, CrewAI, eve, Claude Code subagents and Temporal organise work, reviews and decisions.
- [What Is a Domain-Specific Harness?](https://obversa.ai/docs/glossary/domain-specific-harness.md): The loop, the tools and the rules that make a general model useful for one job. Most of it is process, and in code that process is a workflow.
- [What Is a Software Factory?](https://obversa.ai/docs/glossary/software-factory.md): What people search for. What runs is a writer, a reviewer, tests as commands, and a person at the merge.
- [What Is an Agent Harness?](https://obversa.ai/docs/glossary/agent-harness.md): The software around a model that turns it into an agent. Claude Code, Codex and their kin are agent harnesses; Obversa runs them as a team.
- [What Is a Meta-Harness?](https://obversa.ai/docs/glossary/meta-harness.md): The layer that runs several agent harnesses as a team: roles, handoffs, reviews that run a step again, a person at the gate, and a record.
- [What Is an Agent Pipeline With a Review and a Person?](https://obversa.ai/docs/glossary/agent-pipeline.md): Steps in order, a review that runs the step that owns the fix again, and a person who decides at the end.
- [What Happens When an Agent Crashes Halfway?](https://obversa.ai/docs/glossary/crash-recovery.md): A killed run starts again from its record. Finished steps stay finished; an unfinished one pauses for a person unless it said it was safe to retry.
- [Do I Need Temporal to Survive a Crash?](https://obversa.ai/docs/glossary/durable-execution.md): Not for a run on one machine: a recorded run carries on from its file. Temporal keeps work alive across many workers for days, on a service.
- [Should Another Model Review the Code?](https://obversa.ai/docs/glossary/cross-model-review.md): Yes. Obversa refuses a writer and a reviewer from the same model family when the team is built, and checks the recorded answers again before the reviewers run.
- [How Many Reviewers Have to Accept?](https://obversa.ai/docs/glossary/review-panel.md): As many as you say with agree. Leave it out and every reviewer must accept.
- [Where Does a Person Approve the Change?](https://obversa.ai/docs/glossary/human-approval.md): Yes passes. A no runs the step that owns the fix again. Silence waits.
- [Can an LLM Judge Replace a Person?](https://obversa.ai/docs/glossary/llm-as-judge.md): It can fail a step and pick a winner; it cannot ship the change. A judge score is not an approval.
- [When Should an Agent Eval Loop Stop?](https://obversa.ai/docs/glossary/review-loop.md): When enough reviewers accept, or when the limit you set runs out. Never when the model says it is done.
- [Should Team Rules Live in AGENTS.md?](https://obversa.ai/docs/glossary/workflow-file.md): The rules that shape a session belong there. The team, who does what and what happens on a no, belongs in a workflow file you can run.
- [How Do Two Agents Share One File?](https://obversa.ai/docs/glossary/shared-files.md): They do not. A stage names the files it may write, and parallel attempts run in separate worktrees.
- [API Reference](https://obversa.ai/docs/packages/index.md): Every export a user calls, the package it comes from, and the page that teaches it.
- [Obversa](https://obversa.ai/docs/packages/obversa.md): @obversa/obversa: one dependency that installs the runtime, the runner, the contracts, the workflows, the surfaces, the memory adapters and every engine adapter except Jev, Devin, Mastra and OpenAI Agents.
- [Runtime](https://obversa.ai/docs/packages/runtime.md): @obversa/runtime: declare a team or a graph, review inside it, ask a person, run it and record every step.
- [Runner](https://obversa.ai/docs/packages/runner.md): @obversa/runner: start a stored graph in a worker under a watchdog, read its progress, and resume a recorded pause.
- [API](https://obversa.ai/docs/packages/api.md): @obversa/api: the engine and memory contracts, the graph plan, and the validators for every stored record.
- [Core](https://obversa.ai/docs/packages/core.md): @obversa/core: run one child process to a deadline and get a result you can read whatever the child did.
- [Built-in Workflows](https://obversa.ai/docs/packages/builtin-workflows.md): @obversa/builtin-workflows: three ready-made teams, a writer and reviewer, a review panel, and feature delivery, as jobs for run().
- [Surface](https://obversa.ai/docs/packages/surface.md): @obversa/surface: one loopback server, one session for one decision, one framed result.
- [Surface Diff](https://obversa.ai/docs/packages/surface-diff.md): @obversa/surface-diff: review a Git diff in a browser and get back a decision with line-anchored comments.
- [Engine Options](https://obversa.ai/docs/packages/engines.md): Options every engine takes under the same name: a clean run or your own setup, and the reasoning effort a step runs at.
- [Claude CLI Engine](https://obversa.ai/docs/packages/engine-claude-cli.md): @obversa/engine-claude-cli: Claude Code as a seat, one fresh process per call.
- [Codex CLI Engine](https://obversa.ai/docs/packages/engine-codex-cli.md): @obversa/engine-codex-cli: Codex as a seat, one fresh process per call.
- [Devin CLI Engine](https://obversa.ai/docs/packages/engine-devin-cli.md): @obversa/engine-devin-cli: Devin as a seat, one fresh process per call.
- [Grok CLI Engine](https://obversa.ai/docs/packages/engine-grok-cli.md): @obversa/engine-grok-cli: one engine attempt through a fresh Grok CLI process, with your own Grok login.
- [OpenCode CLI Engine](https://obversa.ai/docs/packages/engine-opencode-cli.md): @obversa/engine-opencode-cli: one engine attempt through a fresh OpenCode CLI process, with your own OpenCode login, for any provider OpenCode runs.
- [Claude Agent SDK Engine](https://obversa.ai/docs/packages/engine-claude-agent-sdk.md): @obversa/engine-claude-agent-sdk: Claude through the Agent SDK, one fresh query() per request, with memory as a tool.
- [Anthropic API Engine](https://obversa.ai/docs/packages/engine-anthropic-api.md): @obversa/engine-anthropic-api: text-only requests straight to the Anthropic Messages API, no process.
- [Jev API Engine](https://obversa.ai/docs/packages/engine-jev-api.md): @obversa/engine-jev-api: typed questions about state your run already recorded, answered by Jev over the TypeSafe API.
- [Mastra Engine](https://obversa.ai/docs/packages/engine-mastra.md): @obversa/engine-mastra: put an agent you built with Mastra on an Obversa team, as one engine.
- [OpenAI Agents Engine](https://obversa.ai/docs/packages/engine-openai-agents.md): @obversa/engine-openai-agents: put an agent you built with the OpenAI Agents SDK on an Obversa team, as one engine.
- [eve Engine](https://obversa.ai/docs/packages/engine-eve.md): Coming soon: an eve agent as one Obversa engine.
- [LangGraph Engine](https://obversa.ai/docs/packages/engine-langgraph.md): Coming soon: a LangGraph agent as one Obversa engine.
- [Git Memory](https://obversa.ai/docs/packages/memory-git.md): @obversa/memory-git: memory in private Git references, and a stage's reasoning written into the commit that carries its change.
- [Simple Memory](https://obversa.ai/docs/packages/memory-simple.md): @obversa/memory-simple: the memory port in one process, for tests and short runs.
- [Markdown Memory](https://obversa.ai/docs/packages/memory-markdown.md): @obversa/memory-markdown: search a folder of Markdown files with no index or service, and hand the hits to ground through a read-only memory view.
- [Webhook Notifications](https://obversa.ai/docs/packages/notify-webhook.md): @obversa/notify-webhook: one message per interesting run event, posted to a URL you supply.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.