Braid is one durable terminal for coding agents.
A portable AgentProfile selects the runner, model, instructions, tools, and permissions.
Braid sends every turn through agent-runtime, then keeps the transcript, branches, approvals, activity, graph, and trace analysis together.
This recording uses a packed Braid artifact and a real Product engineer AgentProfile.
It routes one coding task through Local CLI Bridge to Claude Code and opus.
It verifies the edited workspace, then switches to a Trace analyst AgentProfile on sonnet.
It runs /ask over the frozen trace and renders cited findings, model calls, tokens, cost provenance, and latency.
The capture manifest records the package hash, route, profile, limits, usage, latency, workspace proof, analysis evidence, and artifact hashes.
Braid requires Node.js 22.19 or newer.
Current validated release targets are Linux x64 and macOS arm64.
The package rejects Windows installation until encrypted state meets the required path-race boundary there.
npm install --global @tangle-network/braid
braidThe first-run flow selects an AgentProfile and a connection.
No runner-specific Braid configuration is required.
For an offline terminal walkthrough, use the deterministic fixture.
braid --fixture deterministicThe fixture proves rendering and state transitions only.
It does not prove a live runner, model, connection, inference route, or sandbox.
The core path is deliberately small.
AgentProfile + user turn
│
▼
Braid
│ profile snapshot · connection · run limits
▼
agent-runtime
│
├── CLI Bridge ── Pi · Codex · Claude Code · Kimi Code · OpenCode · other runners
├── Tangle inference
└── Tangle sandbox ── remote workspace and environment lifecycle
│
▼
normalized events, receipts, activity, and final output
Braid does not implement an agent loop, spawn runner processes directly, parse private runner output, or invent another profile format.
A concrete local route is AgentProfile with harness: 'pi' → Braid admission → agent-runtime → a CLI Bridge connection → Pi → normalized events back to Braid.
AgentProfile is the canonical portable definition of one agent.
It can contain the profile name, instructions, model hints, preferred runner, tools, permissions, resources, skills, MCP connections, modes, hooks, and subagent definitions.
The harness field in the SDK is a runner preference.
Braid displays that preference as runner so the profile remains the agent identity while the execution route remains replaceable.
import type { AgentProfile } from '@tangle-network/agent-interface'
const profile: AgentProfile = {
name: 'Release engineer',
harness: 'pi',
model: {
provider: 'tangle-router',
default: 'tangle-router/glm-5.2',
reasoningEffort: 'high',
},
prompt: {
instructions: [
'Inspect the repository before changing it.',
'Run focused checks and report exact evidence.',
],
},
tools: { read: true, write: true, shell: true },
permissions: { read: 'allow', write: 'ask', shell: 'ask' },
}A connection supplies transport and credential references.
The run binds the exact profile snapshot, selected connection, effective runner, model, reasoning effort, output limit, and execution environment before dispatch.
Reasoning effort and maximum output are separate dimensions.
Reasoning effort controls the requested thinking tier when the selected route supports it, while maximum output limits emitted tokens independently.
The main shell and activity details keep these values together without confusing configuration with provider evidence.
The following values illustrate the shape of one receipt and are not a live run result.
| Field | Example value |
|---|---|
| Profile | Release engineer |
| Runner | pi |
| Model | tangle-router/glm-5.2 |
| Reasoning | high |
| Max output | 16,384 tokens |
| Connection | Local CLI Bridge |
| Execution location | local workspace through CLI Bridge |
| Environment | local process; sandbox fields not applicable |
When the route is a Tangle sandbox, Braid shows the environment lifecycle and the resources, placement, and machine details that the provider actually reports.
It labels requested, verified, sampled, estimated, and unavailable values separately.
It never fills an unreported IP address, CPU allocation, RAM value, GPU lease, storage value, or cost with a guess.
Braid keeps direct turns, trace analyses, and runtime workers distinct.
| Activity | What it means | Usage and control |
|---|---|---|
| Turn | A user message admitted to the selected runner | Direct model, tool, latency, and cost values for that run |
| Analysis | A separate agent-eval execution over a frozen run or branch |
Its own analyst profile, model, tokens, latency, cost, citations, and cancellation |
| Worker | A runtime-owned child under a supervisor | Its own status and usage when reported, with parent binding and control capability |
The activity browser can show all three in one timeline while preserving their separate totals.
An unbound supervisor remains workspace activity and is not silently attributed to the current turn.
Missing provider values remain unknown instead of becoming zero.
These commands inspect or compare recorded work rather than sending another ordinary prompt to the active coding runner.
| Command | Meaning |
|---|---|
/ask <question> |
Ask one free-form question about a selected frozen run or branch and return cited findings. |
/analyze <recipe> |
Run a named recipe such as failure, cost, tools, or improvement through agent-eval. |
/compare <left> <right> |
Freeze two run or branch sources, show their measured asymmetries, and create a paired comparison. |
/ask does not append a message to the analyzed branch.
Each analysis has its own run identity, source digest, analyst profile, model, budget, usage, latency, cost, completeness, and citations.
The standard Braid install includes uv for /ask.
On first use, uv downloads a managed Python 3.12 runtime and runs agent-eval-rpc[dspy]==0.144.11 in an isolated cached environment.
Set BRAID_PYTHON only when an operator must use a preinstalled compatible environment instead.
Findings remain separate until the user explicitly sends selected findings to a branch or forks from the analysis.
Interactive mode is the full-screen terminal experience with a multiline composer, streaming transcript, activity pane, selectors, and focused overlays.
Use inline mode when preserving normal terminal scrollback matters.
braid
braid --inlineHeadless mode is the same application core behind JSON Lines commands and state records.
braid rpcUse plain mode for a readable non-interactive event stream without terminal control sequences.
braid --plainThe terminal and JSONL interfaces share command parsing, capability checks, operation identifiers, reducers, persistence, execution ports, and view projections.
Headless clients can send, queue, steer, cancel, detach, reconnect, reconcile, inspect state, inspect activity, run analysis, compare sources, and export records through the versioned protocol.
Mutating headless requests carry stable operation identifiers so a retry can be recognized instead of dispatched twice.
Opening Braid with --conversation <id> attaches the interface to a durable Braid conversation and its recorded run bindings.
That operation restores Braid's journal and view state; it does not claim to take over an arbitrary native runner process.
Braid reconnects a non-terminal run from the last committed event cursor only when the selected provider can prove replay or status.
If the provider cannot prove the live state, Braid displays detached, incomplete, expired, unauthorized, or unknown rather than calling the run completed.
Continuing a compatible native provider session requires provider evidence that its context boundary matches Braid's recorded message boundary.
Changing runners creates a new provider session with an explicit portable-context handoff.
It does not claim to transfer hidden process memory, runner-specific todos, opaque tool state, or native session internals.
A Tangle sandbox connection provides an isolated remote workspace and reports only the lifecycle, replay, control, and resource capabilities that the current provider proves.
Braid shows those capabilities and their receipts through the same activity and graph surfaces.
New Tangle Sandbox connections default to one ephemeral cloud turn and delete that environment after the turn.
Retained lifecycle is an explicit connection configuration option with a bounded idle limit.
Before retained execution creates a sandbox, Braid requires exact control plus provider-backed lookup for an unacknowledged dispatch.
The current published provider does not report that complete contract or lookup, so Braid rejects retained mode without creating a resource.
When the provider reports both, a fresh Braid process can recover before or after the six-field reference commits.
Native follow-up turns remain disabled until the provider also proves that its context boundary matches Braid's recorded boundary.
Checkpoint, environment fork, and interaction response remain unavailable until the shared provider reports and proves those operations.
The user can inspect the requested and verified execution location, but provider-private machine details remain unavailable when they are not reported.
The latest passing production stress proof completed 20 of 20 ephemeral Braid turns through OpenCode, GLM 5.2, and Tangle Sandbox at four-way concurrency.
All 20 remote environments were unique and confirmed deleted, while the account's active Sandbox count returned from four to four.
See the secret-free proof artifact for every run, token receipt, latency, environment observation, and cleanup result.
A later canary found a current platform regression before environment allocation.
Fresh credentials authenticated Sandbox and Router, but the internal model-key step rejected the Sandbox service with HTTP 403.
Braid left zero owned environments, while ADC issue 5277 tracks the platform failure.
Runtime issue 808 tracks the separate ten-minute retry of that permanent rejection.
The verification record keeps the full results, limits, and tracked platform work.
| Need | Command or key |
|---|---|
| Select the agent and route | /profile, /connection, /runner, /model, /effort |
| Inspect execution | /activity, F2, /export |
| Navigate the work graph | /graph, /fork, /branch, /clone |
| Answer or automate a request | /approve, /reject, /automate |
| Control active work | /queue, /steer, /cancel |
| Drive Braid from another process | braid rpc |
Commands remain searchable when a provider does not support them.
An unavailable command explains the missing capability instead of pretending that the operation succeeded.
| Boundary | Owner |
|---|---|
| Portable agent definition and compatibility facts | agent-interface |
| Run admission, lifecycle, normalized events, and runtime control | agent-runtime |
| Local runner process and native profile materialization | CLI Bridge |
| Tangle inference and remote workspace lifecycle | Tangle provider and sandbox packages |
| Trace analysis and paired comparison | agent-eval |
| Conversation journal, branches, graph, approvals, projections, and terminal/headless interfaces | Braid |
Braid adapts these contracts through narrow ports.
It does not duplicate execution, authentication, provider parsing, sandbox scheduling, trace judging, or billing logic.
pnpm install --frozen-lockfile
pnpm check
pnpm capture:visualpnpm check covers formatting, linting, types, dependency boundaries, attribution, licenses, deterministic tests, live checks, and release checks configured by the repository.
pnpm capture:visual drives the built CLI through a pseudo-terminal and records the deterministic terminal evidence required by the verification plan.
The checked-in W6 captures prove deterministic rendering and keyboard paths.
They are not evidence of a live Pi, CLI Bridge, Tangle inference, or Tangle sandbox run.
The verification plan defines the required live, headless, terminal, security, installation, and release evidence.
The delivery plan records dependency order and completion criteria.
The product contract, experience specification, and architecture define the user-visible and ownership boundaries.
Braid uses the MIT-licensed @earendil-works/pi-tui package for terminal rendering and input primitives.
Its interaction design takes narrow, application-level patterns from Pi, OpenCode, and Codex without copying their agent loops, session stores, authentication systems, provider adapters, or model registries.
See the renderer decision, runtime boundary, upstream strategy, and third-party notices for the exact reuse boundary.