Braid is a terminal client over agent-runtime.
It lets one portable AgentProfile drive different coding runners through local CLI Bridge connections, Tangle inference, or Tangle sandboxes.
Braid owns the conversation, transcript, branches, approvals, activity, graph, and trace-analysis experience.
The selected runner owns its native process and session, while agent-runtime owns admission, lifecycle, normalized events, and runtime control.
This 13-second recording comes from a clean install of a freshly packed @tangle-network/braid@0.1.0 artifact.
The installed artifact resolves agent-runtime@0.132.0 and the CLI Bridge provider at 0.6.0 from npm.
It restores the Braid live GLM reviewer AgentProfile and its retained Pi session through Local CLI Bridge.
The user asks Braid to make a generated JavaScript CLI independent of an incompatible parent package configuration.
Braid fixes the project, runs node --test, and reports 11 tests passed with zero failures.
The user then types /activity and opens the retained run receipt.
The receipt shows the AgentProfile, Pi runner, Local CLI Bridge connection, execution environment, provider session, exact GLM-5.2 route, thinking level, tokens, model calls, and measurement completeness.
The run used 28,949 input tokens, 1,943 output tokens, and five model calls.
Cost and model latency remain unknown because this route did not report them.
An independent Node process reran all 11 tests successfully.
A fresh Braid process then restored the same run and transcript from encrypted state and exited with code zero.
The capture summary records the package hash, route, retained identifiers, independent test output, restart result, and artifact hashes.
The Pi and /ask recording shows a second real route followed by cited trace analysis.
Its capture manifest records the exact route, profile, limits, usage, cost, latency, workspace checks, and artifact hashes.
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 another agent loop, spawn runner processes directly, parse private runner output, or invent a second 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.
Braid requires Node.js 22.19 or newer.
npm install --global @tangle-network/braid
braidTo build Braid from source, use pnpm 11.18.
git clone https://github.com/tangle-network/braid.git
cd braid
corepack enable
pnpm install --frozen-lockfile
pnpm build
pnpm exec braidThe first-run flow selects an AgentProfile and a connection without requiring a hand-written runner configuration file.
For an offline deterministic terminal walkthrough, use the explicit fixture mode.
braid --fixture deterministicThe fixture proves Braid rendering and state transitions only.
It does not prove a live runner, model, CLI Bridge, inference, or sandbox integration.
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.
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 can provide an isolated remote workspace, environment lifecycle, checkpoint, fork, replay, and resource metadata when its capabilities report those operations.
Braid shows those capabilities and their receipts through the same activity and graph surfaces.
The user can inspect the requested and verified execution location, but provider-private machine details remain unavailable when they are not reported.
| 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.