Forum AI CLI
@forum-ai/cli 0.4.0 records native sessions through session protocol v2. Use Node.js 24 or later.
npm install -g @forum-ai/[email protected]
forum --version
forum --help
One conversation or workflow session is one browsable recording and evaluation unit. Turns and member traces become evidence fragments inside immutable session revisions. Compaction does not start a new session. Native child sessions remain separate with explicit parent links.
Import a provider
Configure FORUM_BASE_URL and FORUM_IMPORT_TOKEN from Add sessions → Import existing traces. A destination FORUM_API_KEY also works. Keep source credentials local.
forum projects --source langsmith
forum preview --source langsmith --project PROJECT_ID --out preview.json
forum import --plan preview.json
forum continue --plan preview.json --out next-preview.json
Use langfuse or braintrust for those providers. Configure LANGSMITH_API_KEY, BRAINTRUST_API_KEY, or both LANGFUSE_PUBLIC_KEY and LANGFUSE_SECRET_KEY privately.
| Provider | Explicit native session identity |
|---|---|
| LangSmith | extra.metadata.thread_id or extra.metadata.session_id |
| Langfuse | sessionId |
| Braintrust | metadata.thread_id, metadata.session_id, or metadata.conversation_id |
Identity is scoped by provider, endpoint, and project. Missing session identity produces a deterministic standalone session from trace identity. Titles, users, timestamps, and projects alone never establish membership.
Previews default to seven days and up to 100 sessions. Dates select sessions; all available member traces are included, including members outside that period. Inspect membership, counts, limitations, and continuation before import. Provider previews freeze identities and retrieve evidence at import time.
Version 3 previews are required. Regenerate older plans. Continuation skips prior selections without splitting sessions. Use locally generated previews; never run an untrusted plan with credentials.
The private delivery checkpoint binds to the preview and destination. Retry the same command after an interrupted delivery. Changed evidence requires --refresh, which reads current fragment versions before submitting updates. Unknown delivery outcomes retain exact requests for retry; a confirmed conflict permits an explicit refresh.
An import remains active until all selected members arrive. A completed import establishes an immediate cutoff; unresolved boundaries remain explicit and block automatic evaluation. Delivery never enables a schedule or changes selected judges and sampling.
Endpoints and source limits
Use --endpoint for project discovery or preview. Continuation and import retain it.
| Source | Default endpoint |
|---|---|
| LangSmith | https://api.smith.langchain.com |
| Langfuse | https://cloud.langfuse.com |
| Braintrust | https://api.braintrust.dev |
Regional and self-hosted sources require their configured HTTPS origin. Langfuse defaults to its public v2 observation API. Use --langfuse-api v1 for an older deployment. This provider API choice is independent of Forum protocol v2.
Langfuse v2 must return the requested sessionId field. An explicit null permits standalone identity; an omitted field fails. Source-side metadata truncation is disclosed as a limitation. Unsupported responses are rejected rather than guessed.
Previews and provider responses have a 64 MiB safety limit and 100,000-record safeguards. Forum accepts up to 8 MiB per fragment, 64 MiB per upload, and 128 MiB per session. Limits produce explicit errors. No session is silently truncated or split.
Offline bundles
forum import --plan preview.json --bundle evidence.forum.json
forum upload --bundle evidence.forum.json
A forum-session-bundle version 2 contains session fragment uploads. Source retrieval or validation failure prevents a partial offline export. Keep bundles and checkpoints private.
The browser import has a smaller request limit. Use the CLI for larger bundles. Offline bundles are new admission requests; use --refresh to reconcile changed destination fragments explicitly.
Local coding sessions
Read the capture guide for activation, verification, upgrades, and removal.
forum capture setup --runtime codex --scope project
forum history preview --runtime codex --out preview.json
forum history import --plan preview.json
Use claude-code for Claude Code. Live capture begins at activation; historical import is separate. Native phase, compaction, delegation, messages, and tool results remain evidence. Opaque encrypted content stays opaque.
History previews select sessions and freeze available supported closed turns and session-level compaction records. Preview and import summaries count turns and session-level fragments separately. A compaction-only session reports zero turns and is still imported. Identical source copies deduplicate. Conflicting copies remain unresolved. Continuation fails if its source-file snapshot changed; generate a new preview.
Inspect an exact revision
Create a temporary grant in Add sessions → Set up tracing → Verify saved sessions. Set FORUM_INSPECTION_TOKEN privately. Missing credentials use hidden terminal input; noninteractive processes must supply private environment variables.
forum recording inspect --recording RECORDING_ID --revision REVISION
forum recording inspect --recording RECORDING_ID --revision REVISION --out private-session.json
Use identifiers from a receipt. There is no latest-revision default. The first command prints metadata. Export downloads the pinned manifest and each exact fragment version in bounded chunks, verifies checksums, and creates a new mode-0600 file.
Existing files are never overwritten. Failed downloads remove partial output. Remove a partial file after forcibly terminating the process before retrying.
Read grants expire after 30 minutes and can be revoked earlier. They cannot upload, manage credentials, or evaluate. Inspection failure does not repeat an application operation.