Current Phase

documentation

Phases Done

3 / 9

Completion

33%

Re-enter At

existing-solutions

3 completed6 remaining

Pipeline Progress ?
⚪ not started not yet begun
✏️ draft initial version
🔍 in review under review
🚧 in progress actively worked on
⛔ blocked waiting on dependency
✅ done completed
⏭️ skipped not applicable

Foundation

✅Done: completed requirements⚪Not Started: not yet begun existing-solutions⚪Not Started: not yet begun codebase-analysis⚪Not Started: not yet begun feasibility✅Done: completed specification⚪Not Started: not yet begun plan

›

Build

⚪Not Started: not yet begun implementation✅Done: completed testing

›

Ship

⚪Not Started: not yet begun documentation

❓ Open Questions📖 Vocabulary

Requirements: ProviderA source of model completions (Anthropic, OpenAI, Gemini, Bedrock, OpenRouter, etc.). Authentication

Overview

jcode lets users authenticate with a wide range of LLM providers so they can use existing subscriptions (Claude Max, ChatGPT Pro, Gemini) or API keys. The auth layer supports OAuthOpen Authorization flows, API keys, Azure Entra ID, and reuse of external credentials (e.g. Codex or Claude CLI auth files), with a browser-based login flow driven from the CLI (jcode login). This feature was reverse-engineered from the existing codebase during an SDLC sync; it documents already-implemented functionality.

Stakeholders

Stakeholder	Interest
End users	Low-friction login with their existing subscriptions, multi-account support, and clear auth status
Maintainer	Accurate provider catalog, diagnosable auth failures, testable login flows

Functional Requirements

Order rows by priority: Must first, then Should, then May.

ID	Priority	Requirement
FR-1MustThe system shall support logging in to multiple built-in providers, including Anthropic Claude, OpenAI/Codex, Gemini, Azure OpenAI, and OpenAI-compatible API-key providers.	Must	The system shall support logging in to multiple built-in providers, including Anthropic Claude, OpenAI/Codex, Gemini, Azure OpenAI, and OpenAI-compatible API-key providers.
FR-2MustThe system shall support browser-based OAuthOpen Authorization login for providers that require it, including printing an auth URL and running a local callback server.	Must	The system shall support browser-based OAuthOpen Authorization login for providers that require it, including printing an auth URL and running a local callback server.
FR-3MustThe system shall support API-key login for providers that accept keys, via interactive prompt, `--api-key`, or environment variable.	Must	The system shall support API-key login for providers that accept keys, via interactive prompt, `--api-key`, or environment variable.
FR-4MustThe system shall detect and reuse external credentials from other CLIs (e.g. Codex auth.json, Claude .credentials.json) with ask-before-read and symlink rejection.	Must	The system shall detect and reuse external credentials from other CLIs (e.g. Codex auth.json, Claude .credentials.json) with ask-before-read and symlink rejection.
FR-5MustThe system shall store credentials securely (e.g. `~/.jcode/auth.json`, macOS Keychain) and support multiple accounts per provider.	Must	The system shall store credentials securely (e.g. `~/.jcode/auth.json`, macOS Keychain) and support multiple accounts per provider.
FR-6MustThe system shall refresh expired tokens, coordinating refreshes so concurrent requests do not double-refresh.	Must	The system shall refresh expired tokens, coordinating refreshes so concurrent requests do not double-refresh.
FR-7ShouldThe system shall provide auth status and diagnostics (`jcode auth status`, `jcode auth doctor`) and end-to-end auth validation (`jcode auth-test`).	Should	The system shall provide auth status and diagnostics (`jcode auth status`, `jcode auth doctor`) and end-to-end auth validation (`jcode auth-test`).
FR-8ShouldThe system shall support experimental CLI providers (Cursor, GitHub Copilot, Antigravity) and named OpenAI-compatible provider profiles.	Should	The system shall support experimental CLI providers (Cursor, GitHub Copilot, Antigravity) and named OpenAI-compatible provider profiles.
FR-9MayThe system shall allow scriptable login via printed auth URL and callback (`--print-auth-url`, `--callback-url`, `--auth-code`).	May	The system shall allow scriptable login via printed auth URL and callback (`--print-auth-url`, `--callback-url`, `--auth-code`).

Non-Functional Requirements

Order rows by priority: Must first, then Should, then May.

ID	Priority	Category	Requirement
NFR-1MustThe system shall never read credential files through symlinks.	Must	Security	The system shall never read credential files through symlinks.
NFR-2MustThe system shall keep tokens out of logs and error output.	Must	Security	The system shall keep tokens out of logs and error output.
NFR-3ShouldA failed or missing login for one provider shall not prevent using other providers.	Should	Availability	A failed or missing login for one provider shall not prevent using other providers.
NFR-4ShouldThe default provider shall be auto-detected from available credentials.	Should	Usability	The default provider shall be auto-detected from available credentials.

Constraints

Must support both subscription-based (OAuthOpen Authorization) and API-key-based providers in one auth model.
Must run without a hosted auth service; callbacks are handled locally.

Acceptance Criteria

Every FR and NFR shall have at least one acceptance criterion.

Order criteria by FRs first (sorted by ID), then NFRs (sorted by ID).

Acceptance criteria verify how a requirement is proven done, they do not restate it. Write concrete, scenario-based criteria (happy path, edge cases and error states where applicable).

Conflicts

None identified yet.

Open Questions

Which provider/account selection UX should win when multiple credentials are available for the same provider? The current behavior is inferred from code, not verified end to end.

Specification: ProviderA source of model completions (Anthropic, OpenAI, Gemini, Bedrock, OpenRouter, etc.). Authentication

Overview

Auth is implemented in the jcode-base layer (crate jcode-base/src/auth/) and driven by CLI commands in src/cli/login/, src/cli/account.rs, src/cli/auth.rs, and src/cli/auth_test/. The login CLI orchestrates provider-specific flows: OAuthOpen Authorization browser flows with a local callback server, API-key prompts, and external credential detection. Stored credentials live under ~/.jcode/ with platform-appropriate hardening (macOS Keychain where applicable), and a refresh coordinator deduplicates token refreshes. This document was reverse-engineered from the existing codebase during an SDLC sync.

Architecture

src/cli/login.rs ─┐
src/cli/login/   ─┼─► jcode-base/src/auth/ (per-provider modules)
src/cli/auth.rs  ─┤     ├─ claude.rs / codex.rs / gemini.rs / google.rs
src/cli/auth_test ┘     ├─ azure.rs / copilot.rs / cursor.rs / antigravity.rs
                         ├─ external.rs (external credential sources)
                         ├─ oauth.rs + refresh_coordinator.rs
                         └─ doctor.rs (auth diagnostics)
                          │
                          ▼
               ~/.jcode/auth.json, openai-auth.json,
               gemini_oauth.json, external CLIs' stores,
               macOS Keychain

Data Models

Auth State

Field	Type	Constraints	Description
provider_key	string	PK	Identifier of the provider (e.g. `anthropic`, `openai`).
account	string	not null	Account label for multi-account support.
credential	object	not null	ProviderA source of model completions (Anthropic, OpenAI, Gemini, Bedrock, OpenRouter, etc.).-specific token/key material and metadata.
source	enum	not null	e.g. `oauth`, `api-key`, `external`.

API Contracts

CLI: `jcode login [provider]`

Flags: --account, --no-browser, --print-auth-url, --callback-url, --auth-code, --complete, --json, --no-validate, --api-base, --api-key, --api-key-env, --google-access-tier.

Behavior | Description |---|---| | No browser flag | Opens the OAuthOpen Authorization URL in the default browser and starts a local callback server. | | --print-auth-url | Prints the URL and waits for --auth-code to complete the flow. | | --api-key / --api-key-env | Validates and stores an API key directly. |

CLI: `jcode auth status` / `jcode auth doctor`

Reports per-provider auth state and common failure causes.

CLI: `jcode auth-test`

End-to-end auth validation with options --login, --all-configured, --coverage, --context-audit.

Sequences

Browser OAuthOpen Authorization login

User → jcode login → open browser / print URL
User authorizes in browser
ProviderA source of model completions (Anthropic, OpenAI, Gemini, Bedrock, OpenRouter, etc.). → local callback server → auth code
jcode → token exchange → refresh_coordinator → store credential
jcode → validates token (unless --no-validate) → success

Technical Decisions

Decision	Choice	Rationale
Auth lives in `jcode-base`	Downward-closed foundational layer	All upper layers and the CLI can rely on auth without layering issues.
Per-provider modules	One module per provider	Isolates provider-specific OAuthOpen Authorization quirks; experimental providers are clearly separated.
External credential reuse	Read other CLIs' auth files with consent	Lets users reuse subscriptions without maintaining duplicate tokens.
Refresh coordinator	Single coordinated refresh	Avoids concurrent double-refresh storms on shared tokens.
Multiple storage backends	Files + macOS Keychain	Balances portability with platform security.

Risks and Unknowns

External credential formats change without notice when upstream CLIs change.
OAuthOpen Authorization callback flows are hard to test end to end in CIContinuous Integration; most coverage relies on local HTTP test servers and API-key providers.

Out of Scope

A hosted identity service for jcode accounts (the jcode account command is unrelated account/billing surface).
New experimental provider integrations beyond what the codebase already ships.

Test Plan: ProviderA source of model completions (Anthropic, OpenAI, Gemini, Bedrock, OpenRouter, etc.). Authentication

Scope

Covers provider login flows (OAuthOpen Authorization and API key), auth status/diagnostics, external credential detection, and token refresh coordination. Out of scope: live tests against paid providers (guarded behind live_tests).

Unit Tests

ID	Description	Input	Expected Output
TC-1	Login flow against a local HTTP test server for OpenAI-compatible providers	`tests/auth_login_flow.rs` with a local OpenRouter/OpenAI-compat server	ProviderA source of model completions (Anthropic, OpenAI, Gemini, Bedrock, OpenRouter, etc.). authenticated, session usable
TC-2	ProviderA source of model completions (Anthropic, OpenAI, Gemini, Bedrock, OpenRouter, etc.). catalog invariants	`crates/jcode-base/src/provider_catalog_tests.rs`	Catalog entries valid and consistent
TC-3	Registry behavior	`crates/jcode-base/src/registry_tests.rs`	ProviderA source of model completions (Anthropic, OpenAI, Gemini, Bedrock, OpenRouter, etc.). registration works
TC-4	External credential review candidates	`crates/jcode-base/src/auth/*_tests.rs`	Detection and ask-before-read behave correctly
TC-5	Refresh coordination	`crates/jcode-base/src/auth/refresh_coordinator.rs` tests	Concurrent refreshes deduplicate

Integration Tests

ID	Description	Preconditions	Expected Outcome
TC-6	ProviderA source of model completions (Anthropic, OpenAI, Gemini, Bedrock, OpenRouter, etc.). matrix auth/endpoint sweep	`tests/provider_matrix.rs`	All configured providers behave per endpoint state
TC-7	End-to-end auth validation suite	`scripts/test_auth_e2e.sh`	Each provider's login/refresh path passes

Edge Cases and Failure Scenarios

ID	Scenario	Expected Behavior
TC-8	Credential file is a symlink	Detection rejects it (never follows symlinks)
TC-9	Expired token with concurrent requests	Token refreshed exactly once; requests share the result
TC-10	One provider misconfigured	Other providers still work

Test Infrastructure

Local HTTP test server for OpenAI-compatible login flows (used by auth_login_flow.rs).
Script-based e2e suite (scripts/test_auth_e2e.sh).
Live provider tests guarded behind live_tests and not run in CIContinuous Integration by default.

Coverage Matrix

Requirement	Test Cases
FR-1MustThe system shall support logging in to multiple built-in providers, including Anthropic Claude, OpenAI/Codex, Gemini, Azure OpenAI, and OpenAI-compatible API-key providers.	TC-1, TC-2
FR-4MustThe system shall detect and reuse external credentials from other CLIs (e.g. Codex auth.json, Claude .credentials.json) with ask-before-read and symlink rejection.	TC-4, TC-8
FR-6MustThe system shall refresh expired tokens, coordinating refreshes so concurrent requests do not double-refresh.	TC-5, TC-9
FR-7ShouldThe system shall provide auth status and diagnostics (`jcode auth status`, `jcode auth doctor`) and end-to-end auth validation (`jcode auth-test`).	TC-6, TC-7
NFR-1MustThe system shall never read credential files through symlinks.	TC-8

Vocabulary

Domain Terms

Technical Terms

Acronyms and Abbreviations

Abbreviation	Expansion
TUITerminal User Interface	Terminal User Interface
OAuthOpen Authorization	Open Authorization
ONNXOpen Neural Network Exchange	Open Neural Network Exchange
STTSpeech-to-Text	Speech-to-Text
ACPAgent Client Protocol	Agent Client Protocol
SDKSoftware Development Kit	Software Development Kit
D1Cloudflare D1 SQLite database	Cloudflare D1Cloudflare D1 SQLite database SQLite database
IPCInter-Process Communication	Inter-Process Communication
NDJSONNewline-Delimited JSON	Newline-Delimited JSON
DAUDaily Active Users	Daily Active Users
CIContinuous Integration	Continuous Integration
QEQuality Engineering	Quality Engineering

Current Phase

documentation

Phases Done

3 / 9

Completion

33%

Re-enter At

existing-solutions

3 completed6 remaining

Pipeline Progress ?
⚪ not started not yet begun
✏️ draft initial version
🔍 in review under review
🚧 in progress actively worked on
⛔ blocked waiting on dependency
✅ done completed
⏭️ skipped not applicable

Foundation

✅Done: completed requirements⚪Not Started: not yet begun existing-solutions⚪Not Started: not yet begun codebase-analysis⚪Not Started: not yet begun feasibility✅Done: completed specification⚪Not Started: not yet begun plan

›

Build

⚪Not Started: not yet begun implementation✅Done: completed testing

›

Ship

⚪Not Started: not yet begun documentation

❓ Open Questions📖 Vocabulary

Requirements: Context CompactionReducing accumulated context (and the KV cache) when a session grows too large.

Overview

Context compaction keeps long sessions usable by compressing the accumulated context (and provider KV cacheProvider-side key-value cache for repeated prompt prefixes.) when it grows too large. jcode supports reactive, proactive, and semantic compaction strategies, all configurable under the [compaction] config section. This feature was reverse-engineered from the existing codebase during an SDLC sync; it documents already-implemented functionality.

Stakeholders

Stakeholder	Interest
End users	Long-running sessions that stay fast and stay within provider context limits
Maintainer	Predictable compaction behavior that preserves important context

Functional Requirements

Order rows by priority: Must first, then Should, then May.

ID	Priority	Requirement
FR-1MustThe system shall compact a session's context when it approaches the provider context window limit.	Must	The system shall compact a session's context when it approaches the provider context window limit.
FR-2MustThe system shall support multiple compaction strategies: reactive (on threshold), proactive (before it is needed), and semantic.	Must	The system shall support multiple compaction strategies: reactive (on threshold), proactive (before it is needed), and semantic.
FR-3MustThe system shall preserve a summary of the compacted context so later turns retain continuity.	Must	The system shall preserve a summary of the compacted context so later turns retain continuity.
FR-4MustThe system shall record compaction state on the session so resume reflects the compacted context.	Must	The system shall record compaction state on the session so resume reflects the compacted context.
FR-5ShouldThe system shall keep a cache-relevant hash of messages so KV-cache prefix changes are detected after compaction.	Should	The system shall keep a cache-relevant hash of messages so KV-cache prefix changes are detected after compaction.
FR-6ShouldThe system shall allow strategy configuration per the `[compaction]` section (reactive/proactive/semantic).	Should	The system shall allow strategy configuration per the `[compaction]` section (reactive/proactive/semantic).
FR-7MayThe system shall support context-window resolution invariants across providers (respecting per-provider limits).	May	The system shall support context-window resolution invariants across providers (respecting per-provider limits).

Non-Functional Requirements

Order rows by priority: Must first, then Should, then May.

ID	Priority	Category	Requirement
NFR-1MustCompactionReducing accumulated context (and the KV cache) when a session grows too large. must never lose the ability to resume the session.	Must	Reliability	CompactionReducing accumulated context (and the KV cache) when a session grows too large. must never lose the ability to resume the session.
NFR-2ShouldCompactionReducing accumulated context (and the KV cache) when a session grows too large. must be cheap enough to run mid-turn without disrupting the user.	Should	Performance	CompactionReducing accumulated context (and the KV cache) when a session grows too large. must be cheap enough to run mid-turn without disrupting the user.
NFR-3ShouldSessions at the context limit must be able to continue rather than fail.	Should	Availability	Sessions at the context limit must be able to continue rather than fail.

Constraints

CompactionReducing accumulated context (and the KV cache) when a session grows too large. interacts with the KV cacheProvider-side key-value cache for repeated prompt prefixes.; hashes must stay stable for unchanged prefixes.
Context window limits differ per provider.

Acceptance Criteria

Order criteria by FRs first (sorted by ID), then NFRs (sorted by ID).

Conflicts

None identified yet.

Open Questions

What is the exact compaction trigger threshold and how much context is retained? The logic is inferred from compaction.rs and the compaction core crate.

Specification: Context CompactionReducing accumulated context (and the KV cache) when a session grows too large.

Overview

CompactionReducing accumulated context (and the KV cache) when a session grows too large. is implemented in crates/jcode-base/src/compaction.rs (policy and state), crates/jcode-compaction-core (compaction engine), and crates/jcode-app-core/src/agent/compaction.rs (turn-loop integration). The message model supports OpenAICompaction content blocks and cache-relevant message hashes (stable_message_hash, cache_relevant_message_hashes) so KV-cache prefix changes are detected after compaction. This document was reverse-engineered from the existing codebase during an SDLC sync.

Architecture

agent turn loop (app-core/agent/compaction.rs)
   │ checks budget + strategy
   ▼
jcode-base/src/compaction.rs (reactive/proactive/semantic policy, session compaction state)
   │
   ▼
jcode-compaction-core (engine)
   │
   ├── summary preserved in message stream
   ├── session compaction state recorded (StoredCompactionState)
   └── cache-relevant hashes updated for KV-cache correctness

Data Models

CompactionReducing accumulated context (and the KV cache) when a session grows too large. config (`[compaction]`)

Key	Description
reactive	Compact when approaching the limit.
proactive	Compact before it is needed.
semantic	CompactionReducing accumulated context (and the KV cache) when a session grows too large. informed by semantic importance.

CompactionReducing accumulated context (and the KV cache) when a session grows too large.-related message model

Field	Type	Description
OpenAICompaction	ContentBlock	Compacted-context marker in the message stream.
stable_message_hash	string	Stable hash for unchanged prefixes.
cache_relevant_message_hashes	list	Hashes that affect KV-cache prefix validity.

Sequences

Reactive compaction on a turn

TurnOne pass through the agent loop (assistant output, tool execution, provider round-trips). start → context usage checked → limit approached
→ run compaction strategy → compress context → append summary
→ record compaction state on session → update cache-relevant hashes
→ turn continues with compacted context

Technical Decisions

Decision	Choice	Rationale
Multiple strategies	reactive/proactive/semantic	Users tune cost vs. context quality.
Hash-based KV-cache detection	`stable_message_hash` / `cache_relevant_message_hashes`	Prevents stale KV-cache prefixes after compaction.
CompactionReducing accumulated context (and the KV cache) when a session grows too large. core crate	`jcode-compaction-core`	Isolates engine from policy and turn-loop.
CompactionReducing accumulated context (and the KV cache) when a session grows too large. state persisted	`StoredCompactionState`	Resume reflects compacted context.

Risks and Unknowns

CompactionReducing accumulated context (and the KV cache) when a session grows too large. thresholds and retention are not formally documented; inferred from code.
Semantic compaction quality depends on model behavior and embedding importance scoring.

Out of Scope

Lossless long-term context storage beyond the preserved summary.
ProviderA source of model completions (Anthropic, OpenAI, Gemini, Bedrock, OpenRouter, etc.).-specific compaction APIs that are not already integrated.

Test Plan: Context CompactionReducing accumulated context (and the KV cache) when a session grows too large.

Scope

Covers compaction policy, state, KV-cache hash correctness, and context-window resolution invariants. Out of scope: live provider behavior (covered by the context-window matrix suite where applicable).

Unit Tests

ID	Description	Input	Expected Output
TC-1	CompactionReducing accumulated context (and the KV cache) when a session grows too large. policy and state	`crates/jcode-base/src/compaction_tests.rs`	CompactionReducing accumulated context (and the KV cache) when a session grows too large. triggers and records state correctly
TC-2	MessageA single exchange in a session, carrying a role (User/Assistant) and a list of content blocks. cache-relevant hashing	`crates/jcode-message-types` unit tests	Hashes stable for unchanged prefixes, change on compaction
TC-3	Context-window resolution invariants	`tests/context_window_matrix.rs`	Limits resolved per provider invariants

Integration Tests

ID	Description	Preconditions	Expected Outcome
TC-4	Agent-loop compaction	`crates/jcode-app-core/src/agent_tests.rs`	TurnOne pass through the agent loop (assistant output, tool execution, provider round-trips). loop compacts and continues correctly

Edge Cases and Failure Scenarios

ID	Scenario	Expected Behavior
TC-5	SessionA unit of interaction with the agent: a persisted conversation with an id, title, and status. at context limit	Continues via compaction rather than failing
TC-6	CompactionReducing accumulated context (and the KV cache) when a session grows too large. then resume	Compacted state reflected on resume
TC-7	Cache-relevant prefix change	Detected; KV-cache correctness preserved

Test Infrastructure

Context-window matrix suite (tests/context_window_matrix.rs).
MessageA single exchange in a session, carrying a role (User/Assistant) and a list of content blocks.-model unit fixtures.

Coverage Matrix

Requirement	Test Cases
FR-1MustThe system shall compact a session's context when it approaches the provider context window limit.	TC-1, TC-4
FR-4MustThe system shall record compaction state on the session so resume reflects the compacted context.	TC-1, TC-6
FR-5ShouldThe system shall keep a cache-relevant hash of messages so KV-cache prefix changes are detected after compaction.	TC-2, TC-7
FR-7MayThe system shall support context-window resolution invariants across providers (respecting per-provider limits).	TC-3
NFR-1MustCompactionReducing accumulated context (and the KV cache) when a session grows too large. must never lose the ability to resume the session.	TC-6
NFR-3ShouldSessions at the context limit must be able to continue rather than fail.	TC-5

Vocabulary

Domain Terms

Technical Terms

Acronyms and Abbreviations

Abbreviation	Expansion
TUITerminal User Interface	Terminal User Interface
OAuthOpen Authorization	Open Authorization
ONNXOpen Neural Network Exchange	Open Neural Network Exchange
STTSpeech-to-Text	Speech-to-Text
ACPAgent Client Protocol	Agent Client Protocol
SDKSoftware Development Kit	Software Development Kit
D1Cloudflare D1 SQLite database	Cloudflare D1Cloudflare D1 SQLite database SQLite database
IPCInter-Process Communication	Inter-Process Communication
NDJSONNewline-Delimited JSON	Newline-Delimited JSON
DAUDaily Active Users	Daily Active Users
CIContinuous Integration	Continuous Integration
QEQuality Engineering	Quality Engineering

Current Phase

documentation

Phases Done

3 / 9

Completion

33%

Re-enter At

existing-solutions

3 completed6 remaining

Pipeline Progress ?
⚪ not started not yet begun
✏️ draft initial version
🔍 in review under review
🚧 in progress actively worked on
⛔ blocked waiting on dependency
✅ done completed
⏭️ skipped not applicable

Foundation

✅Done: completed requirements⚪Not Started: not yet begun existing-solutions⚪Not Started: not yet begun codebase-analysis⚪Not Started: not yet begun feasibility✅Done: completed specification⚪Not Started: not yet begun plan

›

Build

⚪Not Started: not yet begun implementation✅Done: completed testing

›

Ship

⚪Not Started: not yet begun documentation

❓ Open Questions📖 Vocabulary

Requirements: Agent Memory System

Overview

The agent memory system gives jcode a persistent, searchable memory across sessions. Memories are extracted from sessions, stored in a memory graph, embedded locally with an ONNXOpen Neural Network Exchange MiniLM model, and re-injected into prompts on later turns. A rerank and consolidation pipeline keeps recall relevant and merges memories over time. This feature was reverse-engineered from the existing codebase during an SDLC sync; it documents already-implemented functionality.

Stakeholders

Stakeholder	Interest
End users	The agent remembers project context across sessions and finds relevant past work without manual prompts
Maintainer	Low-footprint local embedding, tunable recall quality, and auditable memory behavior

Functional Requirements

Order rows by priority: Must first, then Should, then May.

ID	Priority	Requirement
FR-1MustThe system shall extract memories from session content for later recall.	Must	The system shall extract memories from session content for later recall.
FR-2MustThe system shall compute local text embeddings for memories using a bundled ONNXOpen Neural Network Exchange MiniLM model so no external embedding API is required.	Must	The system shall compute local text embeddings for memories using a bundled ONNXOpen Neural Network Exchange MiniLM model so no external embedding API is required.
FR-3MustThe system shall store memories in a persistent memory graph and expose memory operations through the CLI (`jcode memory list`, `search`, `export`, `import`, `stats`).	Must	The system shall store memories in a persistent memory graph and expose memory operations through the CLI (`jcode memory list`, `search`, `export`, `import`, `stats`).
FR-4MustThe system shall support both keyword and semantic search over memories.	Must	The system shall support both keyword and semantic search over memories.
FR-5MustThe system shall inject relevant memories into the agent prompt on session turns.	Must	The system shall inject relevant memories into the agent prompt on session turns.
FR-6ShouldThe system shall rerank candidate memories (configurable cadence and votes) to keep recall precise.	Should	The system shall rerank candidate memories (configurable cadence and votes) to keep recall precise.
FR-7ShouldThe system shall consolidate and merge related memories over time, including overnight consolidation.	Should	The system shall consolidate and merge related memories over time, including overnight consolidation.
FR-8MayThe system shall expose a memory sidecar agent for autonomous memory maintenance.	May	The system shall expose a memory sidecar agent for autonomous memory maintenance.

Non-Functional Requirements

Order rows by priority: Must first, then Should, then May.

ID	Priority	Category	Requirement
NFR-1MustLocal embedding inference shall not stall the server; the embedding stack is pinned to optimized profiles.	Must	Performance	Local embedding inference shall not stall the server; the embedding stack is pinned to optimized profiles.
NFR-2MustMemory embeddings and extraction shall run locally without sending session content to third parties.	Must	Privacy	Memory embeddings and extraction shall run locally without sending session content to third parties.
NFR-3ShouldSessionA unit of interaction with the agent: a persisted conversation with an id, title, and status. search shall scale to multi-megabyte session files (SIMD-backed matching).	Should	Performance	SessionA unit of interaction with the agent: a persisted conversation with an id, title, and status. search shall scale to multi-megabyte session files (SIMD-backed matching).
NFR-4ShouldMemory storage must be durable across restarts.	Should	Reliability	Memory storage must be durable across restarts.

Constraints

Embeddings must work out of the box in default builds (the embeddings feature is on by default).
A local embedding backend is required; an openai backend is optional.

Acceptance Criteria

Order criteria by FRs first (sorted by ID), then NFRs (sorted by ID).

Conflicts

None identified yet.

Open Questions

What is the exact recall budget per turn (how many memories are injected and at what token cost)? The tuning knobs exist in config but the defaults are inferred from code.

Specification: Agent Memory System

Overview

The memory system lives in crates/jcode-base/src/memory/ (activity, cache, pending) with the extraction agent and graph logic in memory.rs, memory_agent.rs, memory_graph.rs, and memory_rerank.rs. Local embeddings come from the jcode-embedding crate (tract ONNXOpen Neural Network Exchange inference of all-MiniLM-L6-v2). Recall and injection happen in the agent turn loop; consolidation runs as a background/overnight job. This document was reverse-engineered from the existing codebase during an SDLC sync.

Architecture

session turns ──► memory.rs / memory_agent.rs ──► memory graph (persistent)
                       │                                 │
                       ▼                                 ▼
                embedding (ONNXOpen Neural Network Exchange MiniLM)          memory_rerank.rs
                       │                                 │
                       ▼                                 ▼
              memory store ──► recall ──► prompt injection on later turns
                                  ▲
                                  │ (overnight consolidation merges memories)

Data Models

Memory Entry

Field	Type	Constraints	Description
id	string	PK	Stable identifier of the memory.
text	string	not null	The memory content.
embedding	vector	backend dependent	Local embedding for semantic recall.
extracted_at	timestamp	not null	When the memory was created.
score	float	rerank output	Rerank score used for ranking.

SessionA unit of interaction with the agent: a persisted conversation with an id, title, and status. Search

Search over multi-megabyte session files uses memchr-based case-insensitive matching (pinned to opt-level = 3).

API Contracts

CLI: `jcode memory list | search | export | import | stats`

list — enumerate stored memories.
search <query> — keyword and/or semantic search.
export / import — serialize/deserialize the memory store.
stats — counts and store health.
clear-test — test-only clearing helper.

Sequences

Recall on a turn

TurnOne pass through the agent loop (assistant output, tool execution, provider round-trips). start → query memory store → keyword + semantic candidates
→ rerank (if due) → select injection set → inject into prompt → run turn

Technical Decisions

Decision	Choice	Rationale
Local ONNXOpen Neural Network Exchange embeddings	`jcode-embedding` with all-MiniLM-L6-v2	Privacy (NFR-2MustMemory embeddings and extraction shall run locally without sending session content to third parties.) and no external API dependency; feature-gated but enabled by default.
`opt-level = 3` pin for embedding stack	tract/ndarray/tokenizers pinned	Unoptimized inference measured ~666 ms per embed; optimized keeps the agent loop responsive.
Memory as graph + store	`memory_graph.rs` plus durable store	Supports consolidation and relationship-aware recall.
Rerank with cadence/votes	`memory_rerank.rs`	Keeps recall precise at a tunable cost.

Risks and Unknowns

The exact default recall budget and rerank cadence are not documented; behavior was inferred from config and code.
Memory extraction quality depends on the extraction agent's prompt, which may drift with model updates.

Out of Scope

Cloud-hosted memory sync (a Jade cloud integration exists elsewhere but is not part of this subsystem).
EmbeddingA numeric vector representing text, computed locally with an ONNX MiniLM model. backends beyond local ONNXOpen Neural Network Exchange and the optional OpenAI backend.

Test Plan: Agent Memory System

Scope

Covers memory extraction, embedding, storage, search, reranking, and injection. Out of scope: live provider round-trips and real-model quality evaluation (guarded behind dedicated cohorts and scripts).

Unit Tests

ID	Description	Input	Expected Output
TC-1	Memory store operations	`crates/jcode-base/src/memory_tests.rs`	Store persists and recalls memories correctly
TC-2	Memory extraction agent behavior	`crates/jcode-base/src/memory_agent_tests.rs`	Agent produces valid memory candidates
TC-3	SessionA unit of interaction with the agent: a persisted conversation with an id, title, and status. search scoring	`crates/jcode-session-types/src/session_search_tests.rs`	Results ranked correctly

Integration Tests

ID	Description	Preconditions	Expected Outcome
TC-4	EmbeddingA numeric vector representing text, computed locally with an ONNX MiniLM model. numeric stability across inference engines	CIContinuous Integration `minilm_embedding_is_numerically_stable_across_inference_engines` cohort	Embeddings stable across engines
TC-5	Memory e2e flows	`scripts/test_memory.py`	Extract/search/recall works end to end

Edge Cases and Failure Scenarios

ID	Scenario	Expected Behavior
TC-6	Empty memory store	Search returns no results without error
TC-7	Very large session files	Search still responsive (SIMD path)

Test Infrastructure

Python script suite (scripts/test_memory.py).
CIContinuous Integration numeric-stability cohort for embeddings.
jcode memory clear-test helper for sandboxed runs.

Coverage Matrix

Requirement	Test Cases
FR-1MustThe system shall extract memories from session content for later recall.	TC-2
FR-2MustThe system shall compute local text embeddings for memories using a bundled ONNXOpen Neural Network Exchange MiniLM model so no external embedding API is required.	TC-4
FR-3MustThe system shall store memories in a persistent memory graph and expose memory operations through the CLI (`jcode memory list`, `search`, `export`, `import`, `stats`).	TC-1
FR-4MustThe system shall support both keyword and semantic search over memories.	TC-3, TC-5
NFR-2MustMemory embeddings and extraction shall run locally without sending session content to third parties.	TC-4
NFR-3ShouldSessionA unit of interaction with the agent: a persisted conversation with an id, title, and status. search shall scale to multi-megabyte session files (SIMD-backed matching).	TC-7

Vocabulary

Domain Terms

Technical Terms

Acronyms and Abbreviations

Abbreviation	Expansion
TUITerminal User Interface	Terminal User Interface
OAuthOpen Authorization	Open Authorization
ONNXOpen Neural Network Exchange	Open Neural Network Exchange
STTSpeech-to-Text	Speech-to-Text
ACPAgent Client Protocol	Agent Client Protocol
SDKSoftware Development Kit	Software Development Kit
D1Cloudflare D1 SQLite database	Cloudflare D1Cloudflare D1 SQLite database SQLite database
IPCInter-Process Communication	Inter-Process Communication
NDJSONNewline-Delimited JSON	Newline-Delimited JSON
DAUDaily Active Users	Daily Active Users
CIContinuous Integration	Continuous Integration
QEQuality Engineering	Quality Engineering

Current Phase

documentation

Phases Done

3 / 9

Completion

33%

Re-enter At

existing-solutions

3 completed6 remaining

Pipeline Progress ?
⚪ not started not yet begun
✏️ draft initial version
🔍 in review under review
🚧 in progress actively worked on
⛔ blocked waiting on dependency
✅ done completed
⏭️ skipped not applicable

Foundation

✅Done: completed requirements⚪Not Started: not yet begun existing-solutions⚪Not Started: not yet begun codebase-analysis⚪Not Started: not yet begun feasibility✅Done: completed specification⚪Not Started: not yet begun plan

›

Build

⚪Not Started: not yet begun implementation✅Done: completed testing

›

Ship

⚪Not Started: not yet begun documentation

❓ Open Questions📖 Vocabulary

Requirements: SwarmMulti-agent coordination where a coordinator delegates tasks to worker agents. Multi-Agent Coordination

Overview

SwarmMulti-agent coordination where a coordinator delegates tasks to worker agents. coordination lets jcode delegate work across multiple agent instances. A coordinator agent builds a plan DAG of tasks, spawns worker agents (visible, headless, inline, or auto spawn modes), and communicates with them over typed comm channels (direct messages, broadcasts, and plan updates). Members report progress and completion back so the coordinator can revise the plan. This feature was reverse-engineered from the existing codebase during an SDLC sync; it documents already-implemented functionality.

Stakeholders

Stakeholder	Interest
End users	Parallel, coordinated multi-agent work on complex tasks with visible progress
Maintainer	Reliable task graph execution, persisted swarm state, and debuggable comm flows

Functional Requirements

Order rows by priority: Must first, then Should, then May.

ID	Priority	Requirement
FR-1MustThe system shall let a coordinator agent delegate tasks to worker agents within a session.	Must	The system shall let a coordinator agent delegate tasks to worker agents within a session.
FR-2MustThe system shall maintain a plan DAG of tasks (up to a bounded number of plan items) that the coordinator can revise as work completes.	Must	The system shall maintain a plan DAG of tasks (up to a bounded number of plan items) that the coordinator can revise as work completes.
FR-3MustThe system shall support multiple spawn modes for workers: visible, headless, inline, and auto.	Must	The system shall support multiple spawn modes for workers: visible, headless, inline, and auto.
FR-4MustThe system shall provide typed comm channels for messages between the coordinator and members, including direct messages and broadcasts.	Must	The system shall provide typed comm channels for messages between the coordinator and members, including direct messages and broadcasts.
FR-5MustThe system shall surface swarm status and plan progress to the UI (swarm status, plan, todo items).	Must	The system shall surface swarm status and plan progress to the UI (swarm status, plan, todo items).
FR-6MustThe system shall persist swarm state so it survives reloads.	Must	The system shall persist swarm state so it survives reloads.
FR-7ShouldThe system shall validate member reports (including a tldr rule and completion-report marker) before accepting them.	Should	The system shall validate member reports (including a tldr rule and completion-report marker) before accepting them.
FR-8MayThe system shall support an inline gallery of swarm members in the UI.	May	The system shall support an inline gallery of swarm members in the UI.

Non-Functional Requirements

Order rows by priority: Must first, then Should, then May.

ID	Priority	Category	Requirement
NFR-1MustSwarmMulti-agent coordination where a coordinator delegates tasks to worker agents. state must be durable across server reloads and restarts.	Must	Reliability	SwarmMulti-agent coordination where a coordinator delegates tasks to worker agents. state must be durable across server reloads and restarts.
NFR-2ShouldComm messages must flow without blocking the main agent turn loop.	Should	Performance	Comm messages must flow without blocking the main agent turn loop.
NFR-3ShouldThe user shall be able to see each member's status and the overall plan at a glance.	Should	Usability	The user shall be able to see each member's status and the overall plan at a glance.

Constraints

The plan DAG is bounded (MAX_PLAN_ITEMS = 1024).
SwarmMulti-agent coordination where a coordinator delegates tasks to worker agents. behavior is configured under the [agents] config section (spawn mode, swarm model).

Acceptance Criteria

Order criteria by FRs first (sorted by ID), then NFRs (sorted by ID).

Conflicts

None identified yet.

Open Questions

What is the default worker limit and how are tasks balanced across members? Config exposes a swarm model and spawn mode but the scheduling heuristics are inferred from code.

Specification: SwarmMulti-agent coordination where a coordinator delegates tasks to worker agents. Multi-Agent Coordination

Overview

SwarmMulti-agent coordination where a coordinator delegates tasks to worker agents. coordination spans crates/jcode-swarm-core (message/report validation), crates/jcode-plan (plan DAG and mermaid/bridge helpers), crates/jcode-task-types, and the server-side swarm implementation in crates/jcode-app-core/src/server/ (swarm*.rs and comm_*.rs). The coordinator agent runs in the main session; workers run as subagents. This document was reverse-engineered from the existing codebase during an SDLC sync.

Architecture

              coordinator agent (main session)
                        │
          plan DAG (jcode-plan, PlanItem, VersionedPlan)
                        │
   ┌────────────────────┼─────────────────────┐
   ▼                    ▼                     ▼
worker agent        worker agent          worker agent
(visible/headless/inline/auto spawn modes)
   │                    │                     │
   └──────────── typed comm channels (comm_graph, comm_plan, comm_session,
                  comm_control, comm_sync, comm_await) ────────────┘
                        │
              swarm status / plan events ──► UI (TUITerminal User Interface / protocol)

Data Models

PlanItem / VersionedPlan (`crates/jcode-plan`)

Field	Type	Constraints	Description
item	PlanItem	bounded by MAX_PLAN_ITEMS = 1024	A single task node in the plan.
version	int	not null	Version of the plan graph.
status	enum	pending/in-progress/done/failed	Progress of the item.

SwarmMulti-agent coordination where a coordinator delegates tasks to worker agents. Status / Todo / Member

Shared types include SwarmMemberStatus, SwarmTodoItem, and PlanGraphStatus in jcode-protocol.

API Contracts

Protocol (internal)

RunSubagent request — spawn a worker from the coordinator.
Comm* requests — swarm message operations (send DM, broadcast, plan update).
ServerEvent swarm variants — swarm_status, swarm_plan, member status snapshots.

Sequences

Delegate and complete a task

Coordinator → RunSubagent(task) → worker spawns in configured mode
Worker runs task → completion report (tldr + marker)
Server validates report (jcode-swarm-core) → sends Comm message to coordinator
Coordinator updates plan DAG → plan status events stream to UI

Technical Decisions

Decision	Choice	Rationale
Plan as versioned DAG	`VersionedPlan` in `jcode-plan`	Supports revision as tasks complete and replay/history.
Typed comm channels	`comm_*.rs` modules with graph/plan/session/control separation	Keeps message flows auditable and testable.
Report validation	tldr rule + completion marker	Prevents malformed member output from corrupting the plan.
Spawn modes	visible/headless/inline/auto	Lets users trade visibility against parallelism.
Persistence	swarm state in durable server state	Survives reloads (NFR-1MustSwarmMulti-agent coordination where a coordinator delegates tasks to worker agents. state must be durable across server reloads and restarts.).

Risks and Unknowns

Scheduling and parallelism heuristics are not fully documented in the code; inferred from module structure.
Plan-item limits and tldr rules may need tuning as worker counts grow.

Out of Scope

Cross-machine (distributed) swarm execution; workers run within one server process.
Persistent worker identity across sessions.

Test Plan: SwarmMulti-agent coordination where a coordinator delegates tasks to worker agents. Multi-Agent Coordination

Scope

Covers swarm persistence, comm channels, plan graph handling, and member report validation. Out of scope: live multi-agent behavior against paid providers (covered by scripted e2e suites).

Unit Tests

ID	Description	Input	Expected Output
TC-1	SwarmMulti-agent coordination where a coordinator delegates tasks to worker agents. state persistence	`crates/jcode-app-core/src/server/swarm_persistence_tests.rs`	SwarmMulti-agent coordination where a coordinator delegates tasks to worker agents. survives reload/restart
TC-2	Comm channelA message channel between swarm members (direct message, broadcast). behavior	`crates/jcode-app-core/src/server/client_comm_tests.rs`, `comm_control_tests.rs`	Messages delivered to the right members
TC-3	Comm plan graph handling	`crates/jcode-app-core/src/server/comm_plan_tests.rs`	Plan updates propagate
TC-4	Comm session handling	`crates/jcode-app-core/src/server/comm_session_tests.rs`	SessionA unit of interaction with the agent: a persisted conversation with an id, title, and status.-level comm works
TC-5	Plan DAG invariants	`crates/jcode-plan` tests	Plan stays bounded and versioned

Integration Tests

ID	Description	Preconditions	Expected Outcome
TC-6	SwarmMulti-agent coordination where a coordinator delegates tasks to worker agents. e2e scenarios	`scripts/test_swarm.py`, `scripts/test_swarm_debug.py`	Coordinator + workers complete a delegated task
TC-7	SwarmMulti-agent coordination where a coordinator delegates tasks to worker agents. performance benchmark	`scripts/benchmark_swarm.py`	Throughput/latency within expectations

Edge Cases and Failure Scenarios

ID	Scenario	Expected Behavior
TC-8	Malformed member completion report	Rejected or flagged per tldr/marker rules
TC-9	Plan exceeds item limit	Plan bounded at MAX_PLAN_ITEMS without corruption
TC-10	ReloadHot-reloading the server into a new binary without dropping clients or sessions. mid-task	SwarmMulti-agent coordination where a coordinator delegates tasks to worker agents. state restored; task not lost

Test Infrastructure

Script-based swarm suites (test_swarm.py, test_swarm_debug.py, benchmark_swarm.py).
Durable-state fixtures for reload tests.

Coverage Matrix

Requirement	Test Cases
FR-2MustThe system shall maintain a plan DAG of tasks (up to a bounded number of plan items) that the coordinator can revise as work completes.	TC-3, TC-5, TC-9
FR-4MustThe system shall provide typed comm channels for messages between the coordinator and members, including direct messages and broadcasts.	TC-2, TC-4
FR-6MustThe system shall persist swarm state so it survives reloads.	TC-1, TC-10
FR-7ShouldThe system shall validate member reports (including a tldr rule and completion-report marker) before accepting them.	TC-8
NFR-1MustSwarmMulti-agent coordination where a coordinator delegates tasks to worker agents. state must be durable across server reloads and restarts.	TC-1, TC-10

Vocabulary

Domain Terms

Technical Terms

Acronyms and Abbreviations

Abbreviation	Expansion
TUITerminal User Interface	Terminal User Interface
OAuthOpen Authorization	Open Authorization
ONNXOpen Neural Network Exchange	Open Neural Network Exchange
STTSpeech-to-Text	Speech-to-Text
ACPAgent Client Protocol	Agent Client Protocol
SDKSoftware Development Kit	Software Development Kit
D1Cloudflare D1 SQLite database	Cloudflare D1Cloudflare D1 SQLite database SQLite database
IPCInter-Process Communication	Inter-Process Communication
NDJSONNewline-Delimited JSON	Newline-Delimited JSON
DAUDaily Active Users	Daily Active Users
CIContinuous Integration	Continuous Integration
QEQuality Engineering	Quality Engineering

Current Phase

documentation

Phases Done

3 / 9

Completion

33%

Re-enter At

existing-solutions

3 completed6 remaining

Pipeline Progress ?
⚪ not started not yet begun
✏️ draft initial version
🔍 in review under review
🚧 in progress actively worked on
⛔ blocked waiting on dependency
✅ done completed
⏭️ skipped not applicable

Foundation

✅Done: completed requirements⚪Not Started: not yet begun existing-solutions⚪Not Started: not yet begun codebase-analysis⚪Not Started: not yet begun feasibility✅Done: completed specification⚪Not Started: not yet begun plan

›

Build

⚪Not Started: not yet begun implementation✅Done: completed testing

›

Ship

⚪Not Started: not yet begun documentation

❓ Open Questions📖 Vocabulary

Requirements: Terminal UI

Overview

The terminal UI is jcode's primary interface: a fast, memory-efficient TUITerminal User Interface built with ratatui that renders streaming agent output, session pickers, info widgets, side panels, inline images, and MermaidDiagram rendering inside the terminal. diagrams. It also powers the offline jcode replay video export of past sessions. The TUITerminal User Interface is the presentation layer and shares a backend-neutral render model with the desktop app. This feature was reverse-engineered from the existing codebase during an SDLC sync; it documents already-implemented functionality.

Stakeholders

Stakeholder	Interest
End users	Low-latency, readable streaming output, discoverable keybindings, and useful side panels
Maintainer	Performant rendering under heavy streams, themeable output, and testable UI logic

Functional Requirements

Order rows by priority: Must first, then Should, then May.

ID	Priority	Requirement
FR-1MustThe system shall render streaming agent output in a terminal UI with low input latency.	Must	The system shall render streaming agent output in a terminal UI with low input latency.
FR-2MustThe system shall provide a session picker to browse and resume past sessions.	Must	The system shall provide a session picker to browse and resume past sessions.
FR-3MustThe system shall display info widgets (session info, model, provider, usage) in the UI.	Must	The system shall display info widgets (session info, model, provider, usage) in the UI.
FR-4MustThe system shall support configurable keybindings and display options (e.g. centered mode, message timestamps, theme detection).	Must	The system shall support configurable keybindings and display options (e.g. centered mode, message timestamps, theme detection).
FR-5ShouldThe system shall render side panels such as the session list and usage overlay.	Should	The system shall render side panels such as the session list and usage overlay.
FR-6ShouldThe system shall render MermaidDiagram rendering inside the terminal. diagrams and inline images in the transcript where the terminal supports it.	Should	The system shall render MermaidDiagram rendering inside the terminal. diagrams and inline images in the transcript where the terminal supports it.
FR-7ShouldThe system shall support offline replay of sessions, including video export.	Should	The system shall support offline replay of sessions, including video export.
FR-8ShouldThe system shall run an onboarding walkthrough for first-time users.	Should	The system shall run an onboarding walkthrough for first-time users.
FR-9MayThe system shall show idle animations (e.g. a donut) that stay CPU-light.	May	The system shall show idle animations (e.g. a donut) that stay CPU-light.

Non-Functional Requirements

Order rows by priority: Must first, then Should, then May.

ID	Priority	Category	Requirement
NFR-1MustThe TUITerminal User Interface shall keep full-frame render time low while streaming (render stack pinned to optimized profiles).	Must	Performance	The TUITerminal User Interface shall keep full-frame render time low while streaming (render stack pinned to optimized profiles).
NFR-2MustRAM usage shall stay low; additional clients shall scale memory gracefully.	Must	Performance	RAM usage shall stay low; additional clients shall scale memory gracefully.
NFR-3ShouldKeybindings must be discoverable and configurable without editing source.	Should	Usability	Keybindings must be discoverable and configurable without editing source.
NFR-4ShouldTUITerminal User Interface state must be testable without a live terminal (headless test harness).	Should	Reliability	TUITerminal User Interface state must be testable without a live terminal (headless test harness).

Constraints

Terminal-first: the TUITerminal User Interface must degrade gracefully across terminals without kitty/iterm2 image support.
Config via [keybindings] and [display] sections in ~/.jcode/config.toml.

Acceptance Criteria

Order criteria by FRs first (sorted by ID), then NFRs (sorted by ID).

Conflicts

None identified yet.

Open Questions

What is the exact frame-time budget enforced for the TUITerminal User Interface render stack? Profile comments reference ~12 ms p50 / ~21 ms p95 for full frames, but a formal number is not documented.

Specification: Terminal UI

Overview

The TUITerminal User Interface lives in crates/jcode-tui (the presentation layer of the crate spine: base → app-core → tui → root) with rendering helpers in jcode-tui-mermaid, jcode-tui-anim, jcode-fuzzy, jcode-math, and a shared render model in jcode-render-core. It subscribes to server events over the protocol socket and renders streaming messages, panels, and diagrams. Offline replay/video export lives in jcode-tui's video export module and is reachable via jcode replay. This document was reverse-engineered from the existing codebase during an SDLC sync.

Architecture

jcode-tui (ratatui + crossterm)
├── tui/app/            — main app state machine, keybindings, input handling
├── tui/ui_*            — widget implementations (info widgets, side panels)
├── tui/session_picker  — session browse/resume
├── tui/mermaid         — MermaidDiagram rendering inside the terminal. rendering (PNG via ratatui-image, kitty/sixel/iTerm2/halfblock)
├── tui/video_export    — offline replay + video export (jcode replay)
├── tui/keybind         — configurable keybindings
└── jcode-render-core   — backend-neutral document/render model shared with desktop
        │
        ▼
jcode-protocol (ServerEvent stream over socket)

Data Models

UI State

TUITerminal User Interface state is decomposed into widgets via the TUISTATE trait (see docs/TUISTATE_TRAIT_DECOMPOSITION.md), which keeps rendering logic testable headlessly.

Config Surface

Section	Keys	Description
`[display]`	display modes, centered mode, timestamps, message timestamps	Rendering preferences.
`[keybindings]`	per-action bindings	User-overridable keymaps.
`[features]`	mermaid, idle animation, etc.	Feature toggles.

API Contracts

CLI: `jcode replay [session]`

Flags: --swarm, --export, --video, --auto-edit, --timeline, --speed, --fps.

Behavior | Description |---|---| | --video | Exports an offline video of the session replay. |

Sequences

Render a streaming turn

Server sends ServerEvent (TextDelta, ToolUseStart/End, ...) over socket
TUITerminal User Interface app receives event → updates document model (jcode-render-core)
Redraw triggered → widgets render cells → crossterm frame flush

Technical Decisions

Decision	Choice	Rationale
ratatui + crossterm	Industry-standard terminal rendering	Mature, fast, cross-platform.
Render stack pinned to opt-level 3	ratatui/unicode/image/etc. pinned in profiles	Prevents ~12 ms→21 ms full-frame slowdowns in dev builds.
Backend-neutral render model	`jcode-render-core`	Shares document rendering with the desktop GPU app.
Offline video export	`video_export` module + `jcode replay --video`	Reproducible session review without a live terminal.
TUISTATE decomposition	trait-based widget state	Headless testability (NFR-4ShouldTUITerminal User Interface state must be testable without a live terminal (headless test harness).).

Risks and Unknowns

Image/MermaidDiagram rendering inside the terminal. rendering depends on terminal protocol support; fallbacks degrade to text or halfblock rendering.
Idle animations must stay CPU-light (math kernels pinned to opt-level = 3 to bound CPU use).

Out of Scope

The desktop GPU UI (a separate feature; shares jcode-render-core only).
Terminal-agnostic rendering of exotic diagrams beyond MermaidDiagram rendering inside the terminal..

Test Plan: Terminal UI

Scope

Covers session picker, info widgets, pinned UI state, mermaid rendering, and TUITerminal User Interface serial/test harness behavior. Out of scope: live terminal interaction and image-protocol rendering on physical terminals.

Unit Tests

ID	Description	Input	Expected Output
TC-1	SessionA unit of interaction with the agent: a persisted conversation with an id, title, and status. picker behavior	`crates/jcode-tui/src/tui/session_picker_tests.rs`	Sessions listed and selected correctly
TC-2	Info widgetA TUI panel (session info, model, provider, usage) shown in the interface. rendering	`crates/jcode-tui/src/tui/info_widget_*_tests.rs`	Widgets render expected content
TC-3	Pinned UI state	`crates/jcode-tui/src/tui/ui_pinned_tests.rs`	Pinned elements behave as configured
TC-4	Auth/account pickers	`crates/jcode-tui/src/tui/auth*_tests.rs`	Account pickers render and select correctly
TC-5	TUITerminal User Interface frame timing	`src/bin/tui_bench.rs`	Frame timing within budget

Integration Tests

ID	Description	Preconditions	Expected Outcome
TC-6	Serial TUITerminal User Interface lib tests in CIContinuous Integration	Linux/macOS build matrix	TUITerminal User Interface state tests pass headlessly
TC-7	Desktop2 frame-budget parity	`crates/jcode-desktop2` profile tests	Shared render model stays within budget
TC-8	MermaidDiagram rendering inside the terminal. rendering acceptance	`docs/RENDER_PARITY_ACCEPTANCE_CRITERIA.md` checks	Diagram output matches acceptance criteria

Edge Cases and Failure Scenarios

ID	Scenario	Expected Behavior
TC-9	Terminal without kitty/sixel support	Image/MermaidDiagram rendering inside the terminal. degrades to fallback rendering
TC-10	Rapid streaming with many frames	Input line stays responsive (no visible lag)
TC-11	Empty session list	Picker shows empty state without error

Test Infrastructure

Headless TUITerminal User Interface test harness via TUISTATE trait decomposition.
Benchmark binaries (tui_bench, mermaid_side_panel_probe).
CIContinuous Integration serial TUITerminal User Interface test cohort to avoid terminal flakiness.

Coverage Matrix

Requirement	Test Cases
FR-2MustThe system shall provide a session picker to browse and resume past sessions.	TC-1, TC-11
FR-3MustThe system shall display info widgets (session info, model, provider, usage) in the UI.	TC-2
FR-6ShouldThe system shall render MermaidDiagram rendering inside the terminal. diagrams and inline images in the transcript where the terminal supports it.	TC-8, TC-9
NFR-1MustThe TUITerminal User Interface shall keep full-frame render time low while streaming (render stack pinned to optimized profiles).	TC-5, TC-10
NFR-4ShouldTUITerminal User Interface state must be testable without a live terminal (headless test harness).	TC-6

Vocabulary

Domain Terms

Technical Terms

Acronyms and Abbreviations

Abbreviation	Expansion
TUITerminal User Interface	Terminal User Interface
OAuthOpen Authorization	Open Authorization
ONNXOpen Neural Network Exchange	Open Neural Network Exchange
STTSpeech-to-Text	Speech-to-Text
ACPAgent Client Protocol	Agent Client Protocol
SDKSoftware Development Kit	Software Development Kit
D1Cloudflare D1 SQLite database	Cloudflare D1Cloudflare D1 SQLite database SQLite database
IPCInter-Process Communication	Inter-Process Communication
NDJSONNewline-Delimited JSON	Newline-Delimited JSON
DAUDaily Active Users	Daily Active Users
CIContinuous Integration	Continuous Integration
QEQuality Engineering	Quality Engineering

Current Phase

documentation

Phases Done

3 / 9

Completion

33%

Re-enter At

existing-solutions

3 completed6 remaining

Pipeline Progress ?
⚪ not started not yet begun
✏️ draft initial version
🔍 in review under review
🚧 in progress actively worked on
⛔ blocked waiting on dependency
✅ done completed
⏭️ skipped not applicable

Foundation

✅Done: completed requirements⚪Not Started: not yet begun existing-solutions⚪Not Started: not yet begun codebase-analysis⚪Not Started: not yet begun feasibility✅Done: completed specification⚪Not Started: not yet begun plan

›

Build

⚪Not Started: not yet begun implementation✅Done: completed testing

›

Ship

⚪Not Started: not yet begun documentation

❓ Open Questions📖 Vocabulary

Requirements: SessionA unit of interaction with the agent: a persisted conversation with an id, title, and status. Persistence, Resume and Replay

Overview

Sessions are jcode's durable unit of work. Every session is persisted to disk (a snapshot JSON plus an append-only JSONL journal), so sessions survive crashes, reloads, and reboots. Users can resume sessions by memorable short name, replay past sessions in the TUITerminal User Interface, export them, and even resume sessions started in other tools (Claude Code, Codex, Pi, OpenCode, Cursor). This feature was reverse-engineered from the existing codebase during an SDLC sync; it documents already-implemented functionality.

Stakeholders

Stakeholder	Interest
End users	Never lose a session; resume context across restarts and terminals
Maintainer	Crash-safe persistence, reliable reload recovery, and clean replay/export

Functional Requirements

Order rows by priority: Must first, then Should, then May.

ID	Priority	Requirement
FR-1MustThe system shall persist each session as a snapshot file plus an append-only journal of messages and events.	Must	The system shall persist each session as a snapshot file plus an append-only journal of messages and events.
FR-2MustThe system shall resume a session by id or memorable short name (`--resume`, session picker).	Must	The system shall resume a session by id or memorable short name (`--resume`, session picker).
FR-3MustThe system shall record session status (active, closed, crashed, reloaded, compacted, rate-limited, error) and survive server reloads and restarts.	Must	The system shall record session status (active, closed, crashed, reloaded, compacted, rate-limited, error) and survive server reloads and restarts.
FR-4MustThe system shall import sessions from external tools (Claude Code, Codex, Pi, OpenCode, Cursor) as resume targets.	Must	The system shall import sessions from external tools (Claude Code, Codex, Pi, OpenCode, Cursor) as resume targets.
FR-5MustThe system shall capture an environment snapshot (git state, provider, model) per session.	Must	The system shall capture an environment snapshot (git state, provider, model) per session.
FR-6ShouldThe system shall support TUITerminal User Interface replay of a session, including swarm status and plan events, with export options.	Should	The system shall support TUITerminal User Interface replay of a session, including swarm status and plan events, with export options.
FR-7ShouldThe system shall support a restart snapshot to resume sessions after a reboot.	Should	The system shall support a restart snapshot to resume sessions after a reboot.
FR-8ShouldThe system shall record crash and reload recovery so interrupted sessions can be restored.	Should	The system shall record crash and reload recovery so interrupted sessions can be restored.
FR-9MayThe system shall support session search across persisted sessions.	May	The system shall support session search across persisted sessions.

Non-Functional Requirements

Order rows by priority: Must first, then Should, then May.

ID	Priority	Category	Requirement
NFR-1MustJournal appends shall be crash-safe; a partial journal must not corrupt the session.	Must	Reliability	Journal appends shall be crash-safe; a partial journal must not corrupt the session.
NFR-2MustSessionA unit of interaction with the agent: a persisted conversation with an id, title, and status. files can grow large; persistence and search must not degrade the agent loop.	Must	Performance	SessionA unit of interaction with the agent: a persisted conversation with an id, title, and status. files can grow large; persistence and search must not degrade the agent loop.
NFR-3ShouldResuming should feel instant via memorable names and a picker.	Should	Usability	Resuming should feel instant via memorable names and a picker.

Constraints

Storage layout: ~/.jcode/sessions/<id>.json snapshot plus <id>.journal.jsonl.
Imported sessions keep their provenance (ResumeTarget enum).

Acceptance Criteria

Order criteria by FRs first (sorted by ID), then NFRs (sorted by ID).

Conflicts

None identified yet.

Open Questions

What is the exact journal compaction/truncation policy for very long sessions? CompactionReducing accumulated context (and the KV cache) when a session grows too large. interacts with this feature and the exact boundary is inferred from code.

Specification: SessionA unit of interaction with the agent: a persisted conversation with an id, title, and status. Persistence, Resume and Replay

Overview

SessionA unit of interaction with the agent: a persisted conversation with an id, title, and status. persistence lives in crates/jcode-base/src/session/ (persistence, journal, render, crash) with shared models in crates/jcode-session-types. External-session import is implemented in crates/jcode-import-core. Replay and video export live in the TUITerminal User Interface layer (jcode-tui/src/video_export.rs), reachable via jcode replay. This document was reverse-engineered from the existing codebase during an SDLC sync.

Architecture

jcode server (app-core)
   │ writes
   ▼
~/.jcode/sessions/<id>.json          (snapshot)
~/.jcode/sessions/<id>.journal.jsonl (append-only journal)
   │
   ├── session/ (persistence, journal, render, crash)
   ├── import-core (ResumeTarget: jcode/claude-code/codex/pi/opencode/cursor)
   └── TUITerminal User Interface video_export (jcode replay --video/--export)

Data Models

StoredMessage (`jcode-session-types`)

Field	Type	Constraints	Description
id	string	PK	MessageA single exchange in a session, carrying a role (User/Assistant) and a list of content blocks. id.
role	enum	not null	User or Assistant.
content	list	not null	Content blocks of the message.
token_usage	object	nullable	Token accounting.
timestamp	timestamp	not null	When the message was stored.

SessionJournalMeta

Captures parent id, title, status, compaction state, provider session id, model, reasoning effort, working dir, last pid, timestamps, and flags (canary, debug, saved).

StoredReplayEvent

Kinds: display_message, swarm_status, swarm_plan; appended to the journal for replay.

API Contracts

CLI: `jcode replay [session]`

Flags: --swarm, --export, --video, --auto-edit, --timeline, --speed, --fps.

CLI: `jcode session rename`

Rename a session's title (stored in journal meta).

Sequences

Resume a session

jcode --resume <name|id> → connect to server → load journal → replay events
→ client state rebuilt → stream continues from where it left off

Technical Decisions

Decision	Choice	Rationale
Snapshot + append journal	`<id>.json` + `<id>.journal.jsonl`	Crash-safe appends; snapshot for fast load.
Journal replay events	`StoredReplayEvent`	Reconstructs UI state and swarm plans on resume.
Import from external tools	`ResumeTarget` enum + `jcode-import-core`	Users migrate context from other agents.
Memorable short names	whimsical names (e.g. `fox`)	Fast resume by name (NFR-3ShouldResuming should feel instant via memorable names and a picker.).

Risks and Unknowns

Very long journals interact with compaction; the truncation policy is inferred from code.
Import fidelity depends on external tool formats, which change upstream.

Out of Scope

Cloud-backed session sync (a separate Jade cloud integration).
Editing/deleting persisted history beyond rename and standard lifecycle.

Test Plan: SessionA unit of interaction with the agent: a persisted conversation with an id, title, and status. Persistence, Resume and Replay

Scope

Covers session persistence, journaling, resume, import, replay, and reload recovery. Out of scope: live provider round-trips.

Unit Tests

ID	Description	Input	Expected Output
TC-1	SessionA unit of interaction with the agent: a persisted conversation with an id, title, and status. store behavior	`crates/jcode-base/src/session_tests/`	Sessions persist, load, and resume correctly
TC-2	SessionA unit of interaction with the agent: a persisted conversation with an id, title, and status. search scoring	`crates/jcode-session-types/src/session_search_tests.rs`	Search results ranked correctly
TC-3	External session import	`crates/jcode-base/src/import_tests.rs`	Imported sessions parse and convert correctly

Integration Tests

ID	Description	Preconditions	Expected Outcome
TC-4	End-to-end session flow	`tests/e2e/session_flow.rs`	Create, stream, persist, resume works end to end
TC-5	ReloadHot-reloading the server into a new binary without dropping clients or sessions. multi-client recovery	`tests/e2e/reload_multiclient.rs`	Clients reconnect and sessions survive reload
TC-6	ReloadHot-reloading the server into a new binary without dropping clients or sessions. recovery audit	`scripts/test_reload.py`, `scripts/reload_recovery_audit.py`	Crashed/reloaded sessions recover cleanly

Edge Cases and Failure Scenarios

ID	Scenario	Expected Behavior
TC-7	Corrupted or partial journal	Journal repaired or rejected without corrupting the snapshot
TC-8	Very large session files	Load and search stay responsive
TC-9	Crash mid-write	SessionA unit of interaction with the agent: a persisted conversation with an id, title, and status. marked crashed and recoverable on next start

Test Infrastructure

SessionA unit of interaction with the agent: a persisted conversation with an id, title, and status. fixtures under tests/fixtures/.
Multi-client e2e harness (tests/e2e/test_support/).
Python reload-recovery audit scripts.

Coverage Matrix

Requirement	Test Cases
FR-1MustThe system shall persist each session as a snapshot file plus an append-only journal of messages and events.	TC-1, TC-4
FR-3MustThe system shall record session status (active, closed, crashed, reloaded, compacted, rate-limited, error) and survive server reloads and restarts.	TC-5, TC-9
FR-4MustThe system shall import sessions from external tools (Claude Code, Codex, Pi, OpenCode, Cursor) as resume targets.	TC-3
FR-8ShouldThe system shall record crash and reload recovery so interrupted sessions can be restored.	TC-6, TC-9
FR-9MayThe system shall support session search across persisted sessions.	TC-2
NFR-1MustJournal appends shall be crash-safe; a partial journal must not corrupt the session.	TC-7

Vocabulary

Domain Terms

Technical Terms

Acronyms and Abbreviations

Abbreviation	Expansion
TUITerminal User Interface	Terminal User Interface
OAuthOpen Authorization	Open Authorization
ONNXOpen Neural Network Exchange	Open Neural Network Exchange
STTSpeech-to-Text	Speech-to-Text
ACPAgent Client Protocol	Agent Client Protocol
SDKSoftware Development Kit	Software Development Kit
D1Cloudflare D1 SQLite database	Cloudflare D1Cloudflare D1 SQLite database SQLite database
IPCInter-Process Communication	Inter-Process Communication
NDJSONNewline-Delimited JSON	Newline-Delimited JSON
DAUDaily Active Users	Daily Active Users
CIContinuous Integration	Continuous Integration
QEQuality Engineering	Quality Engineering

Current Phase

documentation

Phases Done

3 / 9

Completion

33%

Re-enter At

existing-solutions

3 completed6 remaining

Pipeline Progress ?
⚪ not started not yet begun
✏️ draft initial version
🔍 in review under review
🚧 in progress actively worked on
⛔ blocked waiting on dependency
✅ done completed
⏭️ skipped not applicable

Foundation

✅Done: completed requirements⚪Not Started: not yet begun existing-solutions⚪Not Started: not yet begun codebase-analysis⚪Not Started: not yet begun feasibility✅Done: completed specification⚪Not Started: not yet begun plan

›

Build

⚪Not Started: not yet begun implementation✅Done: completed testing

›

Ship

⚪Not Started: not yet begun documentation

❓ Open Questions📖 Vocabulary

Requirements: Ambient Mode

Overview

Ambient modeProactive background agent (OpenClaw-style) with work cycles, garden/scout tasks, and overnight processing. is a proactive, OpenClaw-style background agent that works while the user does. A scheduler runs work cycles against configured directives (garden/scout style tasks), executes background tasks, and persists its state. A safety system gates ambient actions, and overnight processing handles long-running consolidation. This feature was reverse-engineered from the existing codebase during an SDLC sync; it documents already-implemented functionality.

Stakeholders

Stakeholder	Interest
End users	A background assistant that makes progress without interrupting the main session
Maintainer	Safe, configurable, observable ambient behavior with strong permissioning

Functional Requirements

Order rows by priority: Must first, then Should, then May.

ID	Priority	Requirement
FR-1MustThe system shall run a background ambient scheduler on the server that executes work cycles.	Must	The system shall run a background ambient scheduler on the server that executes work cycles.
FR-2MustThe system shall execute directives (ambient instructions) and run tasks such as garden/scout activities.	Must	The system shall execute directives (ambient instructions) and run tasks such as garden/scout activities.
FR-3MustThe system shall persist ambient state (status, log, directives) so it survives reloads.	Must	The system shall persist ambient state (status, log, directives) so it survives reloads.
FR-4MustThe system shall gate ambient actions through a safety and permissions system.	Must	The system shall gate ambient actions through a safety and permissions system.
FR-5MustThe system shall expose ambient status and control via the CLI (`jcode ambient status`, `trigger`, `stop`, `log`).	Must	The system shall expose ambient status and control via the CLI (`jcode ambient status`, `trigger`, `stop`, `log`).
FR-6ShouldThe system shall support overnight processing for long-running consolidation jobs.	Should	The system shall support overnight processing for long-running consolidation jobs.
FR-7ShouldThe system shall render ambient status in the TUITerminal User Interface (e.g. via a side panel / badge).	Should	The system shall render ambient status in the TUITerminal User Interface (e.g. via a side panel / badge).
FR-8MayThe system shall trigger ambient activity on configurable schedules.	May	The system shall trigger ambient activity on configurable schedules.

Non-Functional Requirements

Order rows by priority: Must first, then Should, then May.

ID	Priority	Category	Requirement
NFR-1MustAmbient actions shall be subject to the same permission/safety gates as interactive actions.	Must	Safety	Ambient actions shall be subject to the same permission/safety gates as interactive actions.
NFR-2ShouldAmbient work shall not starve interactive turns on the same server.	Should	Performance	Ambient work shall not starve interactive turns on the same server.
NFR-3ShouldAmbient state must be durable across restarts.	Should	Reliability	Ambient state must be durable across restarts.

Constraints

Ambient behavior is configured under the [ambient] config section.
Ambient runs inside the same server process (not a separate daemon).

Acceptance Criteria

Order criteria by FRs first (sorted by ID), then NFRs (sorted by ID).

Conflicts

None identified yet.

Open Questions

What is the default work-cycle cadence and task budget for ambient mode? Config exposes knobs; defaults are inferred from code.

Specification: Ambient Mode

Overview

Ambient modeProactive background agent (OpenClaw-style) with work cycles, garden/scout tasks, and overnight processing. is implemented in crates/jcode-app-core/src/ (ambient.rs, ambient_runner.rs, ambient_scheduler.rs, and the ambient/ module) with shared types in crates/jcode-ambient-types. The scheduler drives work cycles; the runner executes tasks; directives and safety gates control what ambient may do. CLI control lives in src/cli/ (jcode ambient). This document was reverse-engineered from the existing codebase during an SDLC sync.

Architecture

jcode server
└── ambient_scheduler.rs ──► work cycles
        │
        ▼
ambient_runner.rs ──► tasks (garden/scout), directives
        │
        ├── [ambient] config (directives, schedules)
        ├── safety / permissions gates (SAFETY_SYSTEM)
        └── persistence (ambient status + log, durable)
        │
        ▼
CLI: jcode ambient status|log|trigger|stop
TUITerminal User Interface: ambient status side panel / badge

Data Models

Ambient State (`jcode-ambient-types`)

Field	Type	Constraints	Description
status	enum	not null	Running / idle / stopped.
directives	list	not null	Ambient instructions to execute.
log	list	append-only	Recent ambient activity.
schedule	config	nullable	Trigger schedule for cycles.

API Contracts

CLI: `jcode ambient`

status — show ambient mode state.
log — show recent ambient activity.
trigger — run a work cycle now.
stop — stop ambient mode.
run-visible (hidden) — run a cycle visibly for debugging.

Sequences

Work cycle

Scheduler ticks (or trigger) → read directives → pick tasks (garden/scout)
Runner executes task through safety/permission gates
Results logged → state persisted → status events published to UI

Technical Decisions

Decision	Choice	Rationale
Same-process scheduler	`ambient_scheduler.rs` in app-core	No separate daemon; shares server lifecycle.
Safety-gated runner	permissions + command-risk gates	Ambient autonomy must not bypass interactive safety (NFR-1MustAmbient actions shall be subject to the same permission/safety gates as interactive actions.).
Durable ambient state	persisted status/log	Survives reloads (NFR-3ShouldAmbient state must be durable across restarts.).
OvernightScheduled background processing performed while the user is away. hook	overnight processing module	Long-running consolidation fits idle windows.

Risks and Unknowns

Default cycle cadence and per-cycle budgets are inferred from code; they may need operator tuning.
Ambient autonomy against live repositories carries inherent risk; safety coverage is critical.

Out of Scope

A separate ambient daemon or distributed ambient workers.
Ambient actions on behalf of other machines or cloud services.

Test Plan: Ambient Mode

Scope

Covers ambient scheduler, runner, state persistence, and safety gating. Out of scope: real overnight schedules and long-running cycle behavior in CIContinuous Integration.

Unit Tests

ID	Description	Input	Expected Output
TC-1	Ambient state and lifecycle	`crates/jcode-app-core/src/ambient_tests.rs`	Ambient starts, runs, stops, and persists correctly
TC-2	Ambient runner behavior	`crates/jcode-app-core/src/ambient_runner.rs` tests	Tasks execute through the runner
TC-3	Scheduler behavior	`crates/jcode-app-core/src/ambient_scheduler.rs` tests	Cycles trigger on schedule

Integration Tests

ID	Description	Preconditions	Expected Outcome
TC-4	Ambient e2e	`tests/e2e/ambient.rs`	Ambient work cycle runs end to end

Edge Cases and Failure Scenarios

ID	Scenario	Expected Behavior
TC-5	Ambient task requires permission	Action gated by safety system, no bypass
TC-6	Server reload during ambient cycle	Ambient state recovered; cycle resumes
TC-7	Risky command in ambient task	Passed through command-risk gate before execution

Test Infrastructure

E2E harness under tests/e2e/ with test support modules.
Durable-state fixtures for reload scenarios.

Coverage Matrix

Requirement	Test Cases
FR-1MustThe system shall run a background ambient scheduler on the server that executes work cycles.	TC-3, TC-4
FR-2MustThe system shall execute directives (ambient instructions) and run tasks such as garden/scout activities.	TC-2
FR-3MustThe system shall persist ambient state (status, log, directives) so it survives reloads.	TC-1, TC-6
FR-4MustThe system shall gate ambient actions through a safety and permissions system.	TC-5, TC-7
NFR-1MustAmbient actions shall be subject to the same permission/safety gates as interactive actions.	TC-5, TC-7
NFR-3ShouldAmbient state must be durable across restarts.	TC-6

Vocabulary

Domain Terms

Technical Terms

Acronyms and Abbreviations

Abbreviation	Expansion
TUITerminal User Interface	Terminal User Interface
OAuthOpen Authorization	Open Authorization
ONNXOpen Neural Network Exchange	Open Neural Network Exchange
STTSpeech-to-Text	Speech-to-Text
ACPAgent Client Protocol	Agent Client Protocol
SDKSoftware Development Kit	Software Development Kit
D1Cloudflare D1 SQLite database	Cloudflare D1Cloudflare D1 SQLite database SQLite database
IPCInter-Process Communication	Inter-Process Communication
NDJSONNewline-Delimited JSON	Newline-Delimited JSON
DAUDaily Active Users	Daily Active Users
CIContinuous Integration	Continuous Integration
QEQuality Engineering	Quality Engineering

Current Phase

documentation

Phases Done

3 / 9

Completion

33%

Re-enter At

existing-solutions

3 completed6 remaining

Pipeline Progress ?
⚪ not started not yet begun
✏️ draft initial version
🔍 in review under review
🚧 in progress actively worked on
⛔ blocked waiting on dependency
✅ done completed
⏭️ skipped not applicable

Foundation

✅Done: completed requirements⚪Not Started: not yet begun existing-solutions⚪Not Started: not yet begun codebase-analysis⚪Not Started: not yet begun feasibility✅Done: completed specification⚪Not Started: not yet begun plan

›

Build

⚪Not Started: not yet begun implementation✅Done: completed testing

›

Ship

⚪Not Started: not yet begun documentation

❓ Open Questions📖 Vocabulary

Requirements: Harness API and SDKs

Overview

The harness API exposes jcode's agent runtime to external programs through a stable, versioned client API. A Unix-socket bridge (jcode api-bridge) translates versioned API requests onto the internal protocol, and Rust and TypeScript SDKs let applications launch jcode, drive sessions, and stream events. This feature was reverse-engineered from the existing codebase during an SDLC sync; it documents already-implemented functionality.

Stakeholders

Stakeholder	Interest
Application developers	A stable API to embed or script the jcode agent runtime
Maintainer	A versioned API surface that can evolve without breaking SDKSoftware Development Kit clients
Desktop/iOS app teams	Consume sessions and events through the harness API

Functional Requirements

Order rows by priority: Must first, then Should, then May.

ID	Priority	Requirement
FR-1MustThe system shall expose a stable, versioned harness API for launching jcode, driving sessions, and streaming events.	Must	The system shall expose a stable, versioned harness API for launching jcode, driving sessions, and streaming events.
FR-2MustThe system shall serve the API through a Unix-socket bridge (`jcode api-bridge`) built into the released binary.	Must	The system shall serve the API through a Unix-socket bridge (`jcode api-bridge`) built into the released binary.
FR-3MustThe system shall provide a Rust SDKSoftware Development Kit (`jcode-sdk`) for the harness API.	Must	The system shall provide a Rust SDKSoftware Development Kit (`jcode-sdk`) for the harness API.
FR-4MustThe system shall provide a TypeScript SDKSoftware Development Kit (`@1jehuang/jcode-sdk`) published to npm.	Must	The system shall provide a TypeScript SDKSoftware Development Kit (`@1jehuang/jcode-sdk`) published to npm.
FR-5MustThe system shall ship platform launcher packages that let SDKSoftware Development Kit clients launch jcode without a Rust toolchain.	Must	The system shall ship platform launcher packages that let SDKSoftware Development Kit clients launch jcode without a Rust toolchain.
FR-6ShouldThe system shall keep SDKSoftware Development Kit and API behavior consistent (schema parity) between Rust and TypeScript clients.	Should	The system shall keep SDKSoftware Development Kit and API behavior consistent (schema parity) between Rust and TypeScript clients.
FR-7ShouldThe system shall expose session control (start, send message, cancel) and structured events.	Should	The system shall expose session control (start, send message, cancel) and structured events.
FR-8MayThe system shall expose capability coverage and schema snapshots for client-server negotiation.	May	The system shall expose capability coverage and schema snapshots for client-server negotiation.

Non-Functional Requirements

Order rows by priority: Must first, then Should, then May.

ID	Priority	Category	Requirement
NFR-1MustThe API shall be versioned so breaking changes do not silently break existing clients.	Must	Compatibility	The API shall be versioned so breaking changes do not silently break existing clients.
NFR-2MustSDKSoftware Development Kit clients must not need a Rust toolchain to use the API.	Must	Usability	SDKSoftware Development Kit clients must not need a Rust toolchain to use the API.
NFR-3ShouldEvent streaming over the bridge shall be low-overhead (Unix socket framing).	Should	Performance	Event streaming over the bridge shall be low-overhead (Unix socket framing).

Constraints

The bridge is Unix-only (listens on a Unix socket); Windows uses the pipe transport behind the same API.
The bridge ships inside the released binary as jcode api-bridge.

Acceptance Criteria

Order criteria by FRs first (sorted by ID), then NFRs (sorted by ID).

Conflicts

None identified yet.

Open Questions

Which API version is currently current, and what is the deprecation policy for older versions? Versioning exists but the policy is inferred from code.

Specification: Harness API and SDKs

Overview

The harness API is defined in crates/jcode-harness-api (client API, requests, events, capability coverage, schema snapshots) and served by crates/jcode-harness-api-server (the jcode api-bridge binary). The Rust SDKSoftware Development Kit (crates/jcode-sdk) and the TypeScript SDKSoftware Development Kit (sdk/typescript, published as @1jehuang/jcode-sdk) consume the bridge; platform launcher packages live under sdk/npm/. This document was reverse-engineered from the existing codebase during an SDLC sync.

Architecture

SDKSoftware Development Kit clients (Rust: jcode-sdk, TypeScript: @1jehuang/jcode-sdk)
        │
        ▼
jcode api-bridge (jcode-harness-api-server, Unix socket)
        │  framing + translation
        ▼
jcode internal protocol (jcode-protocol)
        │
        ▼
jcode server (agent runtime, sessions, events)

Data Models

Harness API client crate

requests.rs — versioned request types.
events.rs — streamed event types.
capability_coverage.rs — capability negotiation.
schema_snapshot.rs — schema snapshots for parity.

API Contracts

CLI: `jcode api-bridge` (alias `jcode api`, Unix only)

Serves the versioned harness API on a Unix socket for SDKSoftware Development Kit clients.

SDKSoftware Development Kit launch

SDKSoftware Development Kit clients can launch jcode directly; platform launcher packages in sdk/npm/ provide the executable per platform (darwin-arm64, darwin-x64, linux-arm64, linux-x64, win32-arm64, win32-x64).

Sequences

Drive a session from an SDKSoftware Development Kit

SDKSoftware Development Kit → api-bridge (connect, negotiate version) → open session
SDKSoftware Development Kit → send message → server turn loop → events stream back to SDKSoftware Development Kit
SDKSoftware Development Kit → cancel/close session

Technical Decisions

Decision	Choice	Rationale
Versioned client crate	`jcode-harness-api`	Stable surface independent of internal protocol evolution.
Bridge in released binary	`jcode api-bridge`	SDKSoftware Development Kit users need no Rust toolchain (NFR-2MustSDKSoftware Development Kit clients must not need a Rust toolchain to use the API.).
Unix socket bridge	`jcode-harness-api-server`	Low-overhead local IPCInter-Process Communication, versioned framing.
Schema parity testing	`schema-parity.test.ts`, `capability_coverage.rs`	Keeps Rust and TS SDKs consistent (FR-6ShouldThe system shall keep SDKSoftware Development Kit and API behavior consistent (schema parity) between Rust and TypeScript clients.).
Platform launcher packages	`sdk/npm/*`	One install story per platform.

Risks and Unknowns

The bridge is Unix-only by design; Windows support relies on the named-pipe transport behind the same API.
Capability negotiation and version deprecation policy are only partially documented.

Out of Scope

A network-exposed API (bridge is local IPCInter-Process Communication only).
Full parity for every internal protocol feature; the API surface is intentionally smaller.

Test Plan: Harness API and SDKs

Scope

Covers harness API framing, translation, Rust SDKSoftware Development Kit behavior, TypeScript SDKSoftware Development Kit behavior, and schema parity. Out of scope: live long-running sessions in CIContinuous Integration (covered by scripted e2e suites).

Unit Tests

ID	Description	Input	Expected Output
TC-1	Bridge framing	`crates/jcode-harness-api-server/src/framing_tests.rs`	Requests/events frame and unframe correctly
TC-2	Bridge translation	`crates/jcode-harness-api-server/src/translate_tests.rs`	Internal protocol translates to API types
TC-3	Background progress	`crates/jcode-harness-api-server/src/background_progress_tests.rs`	Progress events surface correctly
TC-4	Rust SDKSoftware Development Kit behavior	`crates/jcode-sdk/src/sdk_tests/`	SDKSoftware Development Kit connects, drives sessions, streams events
TC-5	Capability coverage	`crates/jcode-harness-api/src/capability_coverage.rs` tests	Capability negotiation works

Integration Tests

ID	Description	Preconditions	Expected Outcome
TC-6	TypeScript SDKSoftware Development Kit client tests	`sdk/typescript/test/client.test.ts`, `structured.test.ts`, `launch.test.ts`	TS client drives sessions against the bridge
TC-7	SDKSoftware Development Kit schema parity	`sdk/typescript/test/schema-parity.test.ts`	Rust and TS SDKSoftware Development Kit types agree
TC-8	SDKSoftware Development Kit e2e	`scripts/test_sdk_e2e.sh`	End-to-end launch + session flow works
TC-9	SDKSoftware Development Kit package test	`scripts/test_sdk_package.sh`	Published npm tarball imports and works
TC-10	SDKSoftware Development Kit parity in CIContinuous Integration	`ci.yml` SDKSoftware Development Kit parity job	Rust/TS parity gates pass

Edge Cases and Failure Scenarios

ID	Scenario	Expected Behavior
TC-11	Bridge not running	SDKSoftware Development Kit reports a clear connection error
TC-12	Version mismatch between client and server	Negotiation detects incompatible surfaces
TC-13	Cancel mid-turn	Cancel honored, stream stops cleanly

Test Infrastructure

Mock harness for TS tests (sdk/typescript/test/mock-harness.ts).
Live TS test scripts (live-*.mjs) against a real bridge.
scripts/test_sdk_e2e.sh, scripts/test_sdk_package.sh.

Coverage Matrix

Requirement	Test Cases
FR-1MustThe system shall expose a stable, versioned harness API for launching jcode, driving sessions, and streaming events.	TC-1, TC-2, TC-4
FR-3MustThe system shall provide a Rust SDKSoftware Development Kit (`jcode-sdk`) for the harness API.	TC-4
FR-4MustThe system shall provide a TypeScript SDKSoftware Development Kit (`@1jehuang/jcode-sdk`) published to npm.	TC-6
FR-6ShouldThe system shall keep SDKSoftware Development Kit and API behavior consistent (schema parity) between Rust and TypeScript clients.	TC-7, TC-10
FR-7ShouldThe system shall expose session control (start, send message, cancel) and structured events.	TC-13
FR-8MayThe system shall expose capability coverage and schema snapshots for client-server negotiation.	TC-5, TC-12

Vocabulary

Domain Terms

Technical Terms

Acronyms and Abbreviations

Abbreviation	Expansion
TUITerminal User Interface	Terminal User Interface
OAuthOpen Authorization	Open Authorization
ONNXOpen Neural Network Exchange	Open Neural Network Exchange
STTSpeech-to-Text	Speech-to-Text
ACPAgent Client Protocol	Agent Client Protocol
SDKSoftware Development Kit	Software Development Kit
D1Cloudflare D1 SQLite database	Cloudflare D1Cloudflare D1 SQLite database SQLite database
IPCInter-Process Communication	Inter-Process Communication
NDJSONNewline-Delimited JSON	Newline-Delimited JSON
DAUDaily Active Users	Daily Active Users
CIContinuous Integration	Continuous Integration
QEQuality Engineering	Quality Engineering

Current Phase

documentation

Phases Done

3 / 9

Completion

33%

Re-enter At

existing-solutions

3 completed6 remaining

Pipeline Progress ?
⚪ not started not yet begun
✏️ draft initial version
🔍 in review under review
🚧 in progress actively worked on
⛔ blocked waiting on dependency
✅ done completed
⏭️ skipped not applicable

Foundation

✅Done: completed requirements⚪Not Started: not yet begun existing-solutions⚪Not Started: not yet begun codebase-analysis⚪Not Started: not yet begun feasibility✅Done: completed specification⚪Not Started: not yet begun plan

›

Build

⚪Not Started: not yet begun implementation✅Done: completed testing

›

Ship

⚪Not Started: not yet begun documentation

❓ Open Questions📖 Vocabulary

Requirements: Telemetry

Overview

jcode collects opt-out telemetry to understand product health: installation and upgrade funnels, auth success, onboarding progress, session start/end/crash, and turn-end usage. Events are queued client-side in jcode-telemetry-core, sent to https://telemetry.jcode.sh/v1/event, and ingested by a Cloudflare Worker into D1Cloudflare D1 SQLite database for dashboards and analysis. The full disclosure and opt-out model is documented in TELEMETRY.md. This feature was reverse-engineered from the existing codebase during an SDLC sync; it documents already-implemented functionality.

Stakeholders

Stakeholder	Interest
Maintainer	Product-health metrics (DAUDaily Active Users, install funnel, token value) without violating user trust
End users	Clear disclosure of what is and is not collected, and an easy opt-out

Functional Requirements

Order rows by priority: Must first, then Should, then May.

ID	Priority	Requirement
FR-1MustThe system shall emit structured telemetry events for install, upgrade, auth success, onboarding step, feedback, sponsored discovery, session lifecycle, and turn end.	Must	The system shall emit structured telemetry events for install, upgrade, auth success, onboarding step, feedback, sponsored discovery, session lifecycle, and turn end.
FR-2MustThe system shall queue and flush events asynchronously without blocking the agent.	Must	The system shall queue and flush events asynchronously without blocking the agent.
FR-3MustThe system shall respect opt-out via `JCODE_NO_TELEMETRY=1`, `DO_NOT_TRACK=1`, or a file marker.	Must	The system shall respect opt-out via `JCODE_NO_TELEMETRY=1`, `DO_NOT_TRACK=1`, or a file marker.
FR-4MustThe system shall never collect message content, prompts, or responses.	Must	The system shall never collect message content, prompts, or responses.
FR-5MustThe system shall ingest events server-side into a Cloudflare Worker backed by D1Cloudflare D1 SQLite database.	Must	The system shall ingest events server-side into a Cloudflare Worker backed by D1Cloudflare D1 SQLite database.
FR-6ShouldThe system shall provide analytics views (DAUDaily Active Users, install conversion funnel, token value, geography).	Should	The system shall provide analytics views (DAUDaily Active Users, install conversion funnel, token value, geography).
FR-7ShouldThe system shall support schema versioning for events so changes are trackable.	Should	The system shall support schema versioning for events so changes are trackable.
FR-8ShouldThe system shall capture session end reasons (including crashes) for reliability analysis.	Should	The system shall capture session end reasons (including crashes) for reliability analysis.

Non-Functional Requirements

Order rows by priority: Must first, then Should, then May.

ID	Priority	Category	Requirement
NFR-1MustEvent payloads must not contain session content or identifying message text.	Must	Privacy	Event payloads must not contain session content or identifying message text.
NFR-2ShouldFailed telemetry sends must not fail the client workflow.	Should	Reliability	Failed telemetry sends must not fail the client workflow.
NFR-3ShouldThe background queue must be bounded and non-blocking.	Should	Performance	The background queue must be bounded and non-blocking.
NFR-4ShouldServer-side ingestion must tolerate bursts (bounded D1Cloudflare D1 SQLite database usage).	Should	Availability	Server-side ingestion must tolerate bursts (bounded D1Cloudflare D1 SQLite database usage).

Constraints

Opt-out must be discoverable and documented (TELEMETRY.md).
Schema and D1Cloudflare D1 SQLite database size must be controlled (migrations, size self-defense).

Acceptance Criteria

Order criteria by FRs first (sorted by ID), then NFRs (sorted by ID).

Conflicts

None identified yet.

Open Questions

What is the retention window for D1Cloudflare D1 SQLite database data and when are aggregates rolled up? Not documented beyond the dashboards.

Specification: Telemetry

Overview

Client-side telemetry lives in crates/jcode-telemetry-core (async queue, lifecycle/onboarding trace, state support) with event structs in crates/jcode-usage-types (Install, Upgrade, Auth, SessionStart, TurnEnd, SessionLifecycle with end reasons, ErrorCounts). Server-side ingestion is a Cloudflare Worker in telemetry-worker/ (worker.js, D1Cloudflare D1 SQLite database schema, 24 migrations). This document was reverse-engineered from the existing codebase during an SDLC sync.

Architecture

client (jcode-telemetry-core, bounded queue cap 2048)
   │  HTTPS POST /v1/event
   ▼
telemetry.jcode.sh (Cloudflare Worker)
   │  validation + schema
   ▼
D1Cloudflare D1 SQLite database database (schema.sql + migrations/0001..0024)
   │
   ▼
dashboards (DAUDaily Active Users, install funnel, token value, geo, health, users, discovery)

Data Models

Event Types (`jcode-usage-types`)

Event	Fields	Description
InstallEvent	platform, version	Install funnel event.
UpgradeEvent	from_version, to_version	Upgrade funnel event.
AuthEvent	provider, method	Auth success/failure.
OnboardingStepEvent	step	Onboarding progress.
SessionLifecycleEvent	reason	Includes `SessionEndReason` (e.g. crash).
TurnEndEvent	usage	TurnOne pass through the agent loop (assistant output, tool execution, provider round-trips).-level token usage.
ErrorCounts	category	Error aggregates.

Events are schema-versioned (schema version 6 in jcode-telemetry-core).

API Contracts

Client -> Worker: `POST https://telemetry.jcode.sh/v1/event`

Body: JSON event object with shared metadata (version, platform, session id, coarse geography added server-side).

Sequences

Event emission

Trigger (install/session start/turn end/...) → build event → push to bounded queue
Background taskServer-side job running independently of the current turn. flushes queue → POST /v1/event → worker validates → D1Cloudflare D1 SQLite database insert
Opt-out env var set → queue disabled → no events emitted

Technical Decisions

Decision	Choice	Rationale
Bounded background queue	`BACKGROUND_QUEUE_CAPACITY: 2048`	Non-blocking, bounded memory (NFR-3ShouldThe background queue must be bounded and non-blocking.).
Cloudflare Worker + D1Cloudflare D1 SQLite database	`telemetry-worker/`	Cheap serverless ingestion with SQL analytics.
Explicit opt-out	env vars or file marker	Trust and compliance (FR-3MustThe system shall respect opt-out via `JCODE_NO_TELEMETRY=1`, `DO_NOT_TRACK=1`, or a file marker.).
No content collection	event structs exclude messages	Privacy boundary (NFR-1MustEvent payloads must not contain session content or identifying message text.).
D1Cloudflare D1 SQLite database size self-defense	migrations + size controls	Keeps cost and availability bounded.

Risks and Unknowns

Server-side dashboards depend on D1Cloudflare D1 SQLite database data quality and retention; retention is not documented.
Opt-out coverage must be re-checked as new event sites are added.

Out of Scope

Individual-session profiling or user tracking beyond aggregate product metrics.
Collection of prompts, responses, or message content by design.

Test Plan: Telemetry

Scope

Covers client-side event emission, queue behavior, opt-out, lifecycle/onboarding tracing, and server-side worker ingestion. Out of scope: production D1Cloudflare D1 SQLite database data volume behavior.

Unit Tests

ID	Description	Input	Expected Output
TC-1	Client telemetry core	`crates/jcode-telemetry-core/src/tests.rs`	Events queue and flush correctly
TC-2	Lifecycle event tracing	`crates/jcode-telemetry-core/src/lifecycle.rs` tests	SessionA unit of interaction with the agent: a persisted conversation with an id, title, and status. lifecycle events produced with correct end reasons
TC-3	Onboarding trace	`crates/jcode-telemetry-core/src/onboarding_trace.rs` tests	Onboarding steps traced correctly
TC-4	Client-side telemetry app-core	`crates/jcode-app-core/src/telemetry_tests.rs`	App-level telemetry integration works
TC-5	Usage accounting	`crates/jcode-app-core/src/usage_tests.rs`	Token usageCounting and limits for tokens consumed against provider subscriptions. totals correct

Integration Tests

ID	Description	Preconditions	Expected Outcome
TC-6	Worker ingestion	`telemetry-worker/test/worker.test.mjs`	Worker validates and stores events
TC-7	Token-value view	`telemetry-worker/test/token-value.test.mjs`	Token-value aggregation works

Edge Cases and Failure Scenarios

ID	Scenario	Expected Behavior
TC-8	Telemetry endpoint down	Client workflow unaffected; send fails silently
TC-9	Queue full	Queue bounded, no unbounded growth
TC-10	Opt-out set	No events emitted

Test Infrastructure

telemetry-worker/test/*.mjs for worker behavior.
Client queue fixtures for boundedness.
Opt-out env-var test scenarios.

Coverage Matrix

Requirement	Test Cases
FR-1MustThe system shall emit structured telemetry events for install, upgrade, auth success, onboarding step, feedback, sponsored discovery, session lifecycle, and turn end.	TC-1, TC-2
FR-2MustThe system shall queue and flush events asynchronously without blocking the agent.	TC-1, TC-8
FR-3MustThe system shall respect opt-out via `JCODE_NO_TELEMETRY=1`, `DO_NOT_TRACK=1`, or a file marker.	TC-10
FR-5MustThe system shall ingest events server-side into a Cloudflare Worker backed by D1Cloudflare D1 SQLite database.	TC-6
FR-7ShouldThe system shall support schema versioning for events so changes are trackable.	TC-6
FR-8ShouldThe system shall capture session end reasons (including crashes) for reliability analysis.	TC-2
NFR-2ShouldFailed telemetry sends must not fail the client workflow.	TC-8
NFR-3ShouldThe background queue must be bounded and non-blocking.	TC-9

Vocabulary

Domain Terms

Technical Terms

Acronyms and Abbreviations

Abbreviation	Expansion
TUITerminal User Interface	Terminal User Interface
OAuthOpen Authorization	Open Authorization
ONNXOpen Neural Network Exchange	Open Neural Network Exchange
STTSpeech-to-Text	Speech-to-Text
ACPAgent Client Protocol	Agent Client Protocol
SDKSoftware Development Kit	Software Development Kit
D1Cloudflare D1 SQLite database	Cloudflare D1Cloudflare D1 SQLite database SQLite database
IPCInter-Process Communication	Inter-Process Communication
NDJSONNewline-Delimited JSON	Newline-Delimited JSON
DAUDaily Active Users	Daily Active Users
CIContinuous Integration	Continuous Integration
QEQuality Engineering	Quality Engineering

Current Phase

documentation

Phases Done

3 / 9

Completion

33%

Re-enter At

existing-solutions

3 completed6 remaining

Pipeline Progress ?
⚪ not started not yet begun
✏️ draft initial version
🔍 in review under review
🚧 in progress actively worked on
⛔ blocked waiting on dependency
✅ done completed
⏭️ skipped not applicable

Foundation

✅Done: completed requirements⚪Not Started: not yet begun existing-solutions⚪Not Started: not yet begun codebase-analysis⚪Not Started: not yet begun feasibility✅Done: completed specification⚪Not Started: not yet begun plan

›

Build

⚪Not Started: not yet begun implementation✅Done: completed testing

›

Ship

⚪Not Started: not yet begun documentation

❓ Open Questions📖 Vocabulary

Requirements: Installation and Auto-Update

Overview

jcode distributes itself through a multi-platform installer plus GitHub Releases, and keeps itself current with an auto-update pipeline that downloads new binaries and hot-reloads the server without dropping sessions. Release automation covers Linux, macOS, and Windows (including signing) and posts release notes to Discord. This feature was reverse-engineered from the existing codebase during an SDLC sync; it documents already-implemented functionality.

Stakeholders

Stakeholder	Interest
End users	Simple one-command install, reliable updates, and painless uninstall on every platform
Maintainer	Reproducible releases, versioned immutable binaries, and safe hot-reload updates

Functional Requirements

Order rows by priority: Must first, then Should, then May.

ID	Priority	Requirement
FR-1MustThe system shall provide one-command installers on Linux, macOS, and Windows (`https://jcode.sh/install` and `install.ps1`).	Must	The system shall provide one-command installers on Linux, macOS, and Windows (`https://jcode.sh/install` and `install.ps1`).
FR-2MustThe system shall provide uninstallers for each platform.	Must	The system shall provide uninstallers for each platform.
FR-3MustThe system shall check for updates against GitHub Releases and support stable and main update channels.	Must	The system shall check for updates against GitHub Releases and support stable and main update channels.
FR-4MustThe system shall download and install new versions into immutable versioned directories (`~/.jcode/builds/versions/<version>/`) and repoint launcher channels.	Must	The system shall download and install new versions into immutable versioned directories (`~/.jcode/builds/versions/<version>/`) and repoint launcher channels.
FR-5MustThe system shall support hot-reloading the server into the new binary without dropping sessions (exec into new binary, clients reconnect).	Must	The system shall support hot-reloading the server into the new binary without dropping sessions (exec into new binary, clients reconnect).
FR-6ShouldThe system shall support local quick releases (`quick-release.sh`) and CIContinuous Integration release automation across platforms.	Should	The system shall support local quick releases (`quick-release.sh`) and CIContinuous Integration release automation across platforms.
FR-7ShouldThe system shall handle divergence gracefully when the local clone and remote differ during a git-pull based update.	Should	The system shall handle divergence gracefully when the local clone and remote differ during a git-pull based update.
FR-8MayThe system shall post release announcements to Discord.	May	The system shall post release announcements to Discord.

Non-Functional Requirements

Order rows by priority: Must first, then Should, then May.

ID	Priority	Category	Requirement
NFR-1MustUpdate must not corrupt the current install if interrupted.	Must	Reliability	Update must not corrupt the current install if interrupted.
NFR-2MustHot-reload must preserve active sessions and clients.	Must	Availability	Hot-reload must preserve active sessions and clients.
NFR-3ShouldDownloads must be validated (signed/hash-checked) before activation.	Should	Security	Downloads must be validated (signed/hash-checked) before activation.
NFR-4ShouldUpdates should be non-intrusive and respect `--no-update`.	Should	Usability	Updates should be non-intrusive and respect `--no-update`.

Constraints

Version layout and launcher symlinks are documented in AGENTS.md install notes.
Release channels: stable and main.

Acceptance Criteria

Order criteria by FRs first (sorted by ID), then NFRs (sorted by ID).

Conflicts

None identified yet.

Open Questions

Are release binaries signed for all platforms, or only Windows? RELEASING.md documents Windows signing; macOS/Linux coverage is inferred.

Specification: Installation and Auto-Update

Overview

Installers live in scripts/ (install.sh, install.ps1, install_release.sh, uninstall.*), release automation in .github/workflows/release.yml and scripts/quick-release.sh, and the update engine in crates/jcode-update-core (download from GitHub Releases, git-pull handling, divergence detection). Hot-reload on update execs the server into a new binary, reusing the same PID and socket. This document was reverse-engineered from the existing codebase during an SDLC sync.

Architecture

User machine
├── launcher: ~/.local/bin/jcode (symlink into builds/current or builds/stable)
├── builds/versions/<version>/jcode  (immutable binaries)
├── builds/stable/jcode              (stable channel)
├── builds/current/jcode             (self-dev channel)
└── scripts/install.sh / install.ps1 / install_release.sh / uninstall.*

Release pipeline
├── .github/workflows/release.yml (Linux/macOS/Windows builds, signing)
├── scripts/quick-release.sh      (local ~2.5-min release)
├── scripts/generate_release_notes.sh
└── scripts/post_discord_release.py

Data Models

Version layout

Path	Role
`~/.jcode/builds/versions/<version>/jcode`	Immutable versioned binary.
`~/.jcode/builds/stable/jcode`	Stable channel pointer.
`~/.jcode/builds/current/jcode`	Self-devCanary self-development mode that runs a freshly built binary on a shared server./source-build channel pointer.
`~/.jcode/builds/shared-server/jcode`	Symlink into a version, used by the shared daemon.

API Contracts

Update check (`jcode-update-core`)

Queries GitHub Releases for the configured channel (stable/main).
Downloads, extracts, and stages the new binary into a versioned directory.
Handles git pull-based source updates with divergence detection.

Sequences

Auto-update hot reload

jcode update → check releases → download + extract → stage into builds/versions/<v>
→ server reload → exec new binary (same PID, same socket) → clients reconnect
→ launcher repointed to new version

Technical Decisions

Decision	Choice	Rationale
Immutable versioned binaries	`builds/versions/<version>/`	Atomic installs and clean rollback.
Exec-based hot reload	reload into new binary	Preserves sessions and socket (NFR-2MustHot-reload must preserve active sessions and clients.).
Separate update crate	`jcode-update-core`	Isolates download/pull/divergence logic.
Install-script funnel	`scripts/install.sh` + telemetry install events	Measures conversion and reach.
Quick vs CIContinuous Integration release	`quick-release.sh` vs `release.yml`	Fast local iteration vs reproducible artifacts.

Risks and Unknowns

Binary signing coverage outside Windows is not fully documented.
Divergence handling for git-pull updates depends on local clone state.

Out of Scope

A system package manager integration (Homebrew exists for macOS; others inferred).
Containerized distribution of the agent runtime.

Test Plan: Installation and Auto-Update

Scope

Covers installer correctness, update conversion, Windows launcher lifecycle, and Discord release posting. Out of scope: live production release flows (verified in CIContinuous Integration release pipeline).

Unit Tests

ID	Description	Input	Expected Output
TC-1	Update core logic	`crates/jcode-update-core` tests	Update download/stage/activate logic works

Integration Tests

ID	Description	Preconditions	Expected Outcome
TC-2	Install conversion	`scripts/test_install_conversion.sh`	Install script converts download to working install
TC-3	Windows launcher install lifecycle	`scripts/test_windows_launcher_install.ps1`	Launcher installs and runs on Windows
TC-4	Release Discord posting	`scripts/test_post_discord_release.py`	Discord post generated correctly
TC-5	Windows smoke in CIContinuous Integration	`windows-smoke.yml`, `freebsd-smoke.yml`	Platform smoke tests pass

Edge Cases and Failure Scenarios

ID	Scenario	Expected Behavior
TC-6	Interrupted download	Current install stays usable; retry safe
TC-7	Divergent local clone during git-pull update	Divergence handled without breaking install
TC-8	ReloadHot-reloading the server into a new binary without dropping clients or sessions. with open sessions	Sessions preserved; clients reconnect

Test Infrastructure

CIContinuous Integration release/smoke workflows (release.yml, windows-smoke.yml, freebsd-smoke.yml).
Python and PowerShell test scripts for install/Discord flows.

Coverage Matrix

Requirement	Test Cases
FR-1MustThe system shall provide one-command installers on Linux, macOS, and Windows (`https://jcode.sh/install` and `install.ps1`).	TC-2
FR-2MustThe system shall provide uninstallers for each platform.	TC-3
FR-5MustThe system shall support hot-reloading the server into the new binary without dropping sessions (exec into new binary, clients reconnect).	TC-8
FR-8MayThe system shall post release announcements to Discord.	TC-4
NFR-1MustUpdate must not corrupt the current install if interrupted.	TC-6
NFR-2MustHot-reload must preserve active sessions and clients.	TC-8

Vocabulary

Domain Terms

Technical Terms

Acronyms and Abbreviations

Abbreviation	Expansion
TUITerminal User Interface	Terminal User Interface
OAuthOpen Authorization	Open Authorization
ONNXOpen Neural Network Exchange	Open Neural Network Exchange
STTSpeech-to-Text	Speech-to-Text
ACPAgent Client Protocol	Agent Client Protocol
SDKSoftware Development Kit	Software Development Kit
D1Cloudflare D1 SQLite database	Cloudflare D1Cloudflare D1 SQLite database SQLite database
IPCInter-Process Communication	Inter-Process Communication
NDJSONNewline-Delimited JSON	Newline-Delimited JSON
DAUDaily Active Users	Daily Active Users
CIContinuous Integration	Continuous Integration
QEQuality Engineering	Quality Engineering

Term	Definition
SessionA unit of interaction with the agent: a persisted conversation with an id, title, and status.	A unit of interaction with the agent: a persisted conversation with an id, title, and status.
MessageA single exchange in a session, carrying a role (User/Assistant) and a list of content blocks.	A single exchange in a session, carrying a role (User/Assistant) and a list of content blocks.
Content block / partA typed piece of a message (text, reasoning, thinking, tool use, tool result, image, compaction).	A typed piece of a message (text, reasoning, thinking, tool use, tool result, image, compaction).
TurnOne pass through the agent loop (assistant output, tool execution, provider round-trips).	One pass through the agent loop (assistant output, tool execution, provider round-trips).
Tool / tool call / tool resultA capability the agent can invoke; the request and its outcome.	A capability the agent can invoke; the request and its outcome.
CompactionReducing accumulated context (and the KV cache) when a session grows too large.	Reducing accumulated context (and the KV cacheProvider-side key-value cache for repeated prompt prefixes.) when a session grows too large.
ProviderA source of model completions (Anthropic, OpenAI, Gemini, Bedrock, OpenRouter, etc.).	A source of model completions (Anthropic, OpenAI, Gemini, Bedrock, OpenRouter, etc.).
TransportThe connection mode to a provider (HTTPS, WebSocket, or Claude CLI).	The connection mode to a provider (HTTPS, WebSocket, or Claude CLI).
Effort / reasoningThe configured reasoning depth for a model.	The configured reasoning depth for a model.
SwarmMulti-agent coordination where a coordinator delegates tasks to worker agents.	Multi-agent coordination where a coordinator delegates tasks to worker agents.
Plan DAG / plan itemThe directed acyclic graph of tasks a swarm coordinator builds.	The directed acyclic graph of tasks a swarm coordinator builds.
Comm channelA message channel between swarm members (direct message, broadcast).	A message channel between swarm members (direct message, broadcast).
Memory graphThe persistent graph of extracted memories, skills, and relationships.	The persistent graph of extracted memories, skills, and relationships.
EmbeddingA numeric vector representing text, computed locally with an ONNX MiniLM model.	A numeric vector representing text, computed locally with an ONNXOpen Neural Network Exchange MiniLM model.
Recall / injectionRetrieving relevant memories and inserting them into the prompt.	Retrieving relevant memories and inserting them into the prompt.
ConsolidationBackground process that merges and strengthens memories over time.	Background process that merges and strengthens memories over time.
Ambient modeProactive background agent (OpenClaw-style) with work cycles, garden/scout tasks, and overnight processing.	Proactive background agent (OpenClaw-style) with work cycles, garden/scout tasks, and overnight processing.
Self-devCanary self-development mode that runs a freshly built binary on a shared server.	CanaryA session or build used to test new code against real usage. self-development mode that runs a freshly built binary on a shared server.
CanaryA session or build used to test new code against real usage.	A session or build used to test new code against real usage.
ReloadHot-reloading the server into a new binary without dropping clients or sessions.	Hot-reloading the server into a new binary without dropping clients or sessions.
Restart snapshotA saved snapshot of sessions and state used to resume after a reboot.	A saved snapshot of sessions and state used to resume after a reboot.
Resume targetAn external session source that can be resumed (jcode, Claude Code, Codex, Pi, OpenCode, Cursor).	An external session source that can be resumed (jcode, Claude Code, Codex, Pi, OpenCode, Cursor).
Pairing / gatewayQR-code pairing of the iOS app to the desktop daemon through a gateway.	QR-code pairing of the iOS app to the desktop daemon through a gateway.
Harness API / API bridgeThe stable versioned client API (`jcode api-bridge`) and the SDKs that consume it.	The stable versioned client API (`jcode api-bridge`) and the SDKs that consume it.

Term	Definition
NDJSONNewline-Delimited JSON	Newline-delimited JSON used as the client-server wire framing.
Unix socket / named pipeLocal IPC transport (Unix sockets, or Windows named pipes behind the same API).	Local IPCInter-Process Communication transport (Unix sockets, or Windows named pipes behind the same API).
Debug socketA secondary socket that broadcasts TUI state for debugging/automation.	A secondary socket that broadcasts TUITerminal User Interface state for debugging/automation.
Session journalAppend-only JSONL log of a session plus a snapshot JSON file under `~/.jcode/sessions/`.	Append-only JSONL log of a session plus a snapshot JSON file under `~/.jcode/sessions/`.
KV cacheProvider-side key-value cache for repeated prompt prefixes.	ProviderA source of model completions (Anthropic, OpenAI, Gemini, Bedrock, OpenRouter, etc.).-side key-value cache for repeated prompt prefixes.
Token usageCounting and limits for tokens consumed against provider subscriptions.	Counting and limits for tokens consumed against provider subscriptions.
Failover / fallback / routeProvider selection, fallback on failure, and routing between providers/models.	ProviderA source of model completions (Anthropic, OpenAI, Gemini, Bedrock, OpenRouter, etc.). selection, fallback on failure, and routing between providers/models.
Service tier / premium modeProvider-specific access tiers (e.g. priority/flex, copilot one/zero).	ProviderA source of model completions (Anthropic, OpenAI, Gemini, Bedrock, OpenRouter, etc.).-specific access tiers (e.g. priority/flex, copilot one/zero).
OAuth / API key / device codeAuthentication methods supported by the login flows.	Authentication methods supported by the login flows.
External credential sourceReusing credentials from other CLIs (e.g. `~/.codex/auth.json`, `~/.claude/.credentials.json`).	Reusing credentials from other CLIs (e.g. `~/.codex/auth.json`, `~/.claude/.credentials.json`).
TUITerminal User Interface	Terminal user interface.
Info widgetA TUI panel (session info, model, provider, usage) shown in the interface.	A TUITerminal User Interface panel (session info, model, provider, usage) shown in the interface.
MermaidDiagram rendering inside the terminal.	Diagram rendering inside the terminal.
Side panelA collapsible TUI panel (e.g. session list, usage overlay).	A collapsible TUITerminal User Interface panel (e.g. session list, usage overlay).
HooksUser-defined scripts fired at lifecycle points (turn start/end, pre-tool gate, session start/end).	User-defined scripts fired at lifecycle points (turn start/end, pre-tool gate, session start/end).
Spawn hookHook that runs when a new session is spawned.	Hook that runs when a new session is spawned.
Background taskServer-side job running independently of the current turn.	Server-side job running independently of the current turn.
OvernightScheduled background processing performed while the user is away.	Scheduled background processing performed while the user is away.
Budget ratchetCI-enforced limits (warnings, panics, code size, etc.) in `scripts/`.	CIContinuous Integration-enforced limits (warnings, panics, code size, etc.) in `scripts/`.

SDLC Status Dashboard

Features

Pipeline Progress ?⚪ not started not yet begun✏️ draft initial version🔍 in review under review🚧 in progress actively worked on⛔ blocked waiting on dependency✅ done completed⏭️ skipped not applicable

Requirements: ProviderA source of model completions (Anthropic, OpenAI, Gemini, Bedrock, OpenRouter, etc.). Authentication

Overview

Stakeholders

Functional Requirements

Non-Functional Requirements

Constraints

Acceptance Criteria

Conflicts

Open Questions

Specification: ProviderA source of model completions (Anthropic, OpenAI, Gemini, Bedrock, OpenRouter, etc.). Authentication

Overview

Architecture

Data Models

Auth State

API Contracts

CLI: jcode login [provider]

CLI: jcode auth status / jcode auth doctor

CLI: jcode auth-test

Sequences

Browser OAuthOpen Authorization login

Technical Decisions

Risks and Unknowns

Out of Scope

Test Plan: ProviderA source of model completions (Anthropic, OpenAI, Gemini, Bedrock, OpenRouter, etc.). Authentication

Scope

Unit Tests

Integration Tests

Edge Cases and Failure Scenarios

Test Infrastructure

Coverage Matrix

requirements

Vocabulary

Domain Terms

Technical Terms

Acronyms and Abbreviations

Pipeline Progress ?⚪ not started not yet begun✏️ draft initial version🔍 in review under review🚧 in progress actively worked on⛔ blocked waiting on dependency✅ done completed⏭️ skipped not applicable

Requirements: Context CompactionReducing accumulated context (and the KV cache) when a session grows too large.

Overview

Stakeholders

Functional Requirements

Non-Functional Requirements

Constraints

Acceptance Criteria

Conflicts

Open Questions

Specification: Context CompactionReducing accumulated context (and the KV cache) when a session grows too large.

Overview

Architecture

Data Models

CompactionReducing accumulated context (and the KV cache) when a session grows too large. config ([compaction])

CompactionReducing accumulated context (and the KV cache) when a session grows too large.-related message model

Sequences

Reactive compaction on a turn

Technical Decisions

Risks and Unknowns

Out of Scope

Test Plan: Context CompactionReducing accumulated context (and the KV cache) when a session grows too large.

Scope

Unit Tests

Integration Tests

Edge Cases and Failure Scenarios

Test Infrastructure

Coverage Matrix

requirements

Vocabulary

Domain Terms

Technical Terms

Acronyms and Abbreviations

Pipeline Progress ?⚪ not started not yet begun✏️ draft initial version🔍 in review under review🚧 in progress actively worked on⛔ blocked waiting on dependency✅ done completed⏭️ skipped not applicable

Requirements: Agent Memory System

Overview

Stakeholders

Functional Requirements

Non-Functional Requirements

Constraints

Acceptance Criteria

Conflicts

Pipeline Progress ?
⚪ not started not yet begun
✏️ draft initial version
🔍 in review under review
🚧 in progress actively worked on
⛔ blocked waiting on dependency
✅ done completed
⏭️ skipped not applicable

CLI: `jcode login [provider]`

CLI: `jcode auth status` / `jcode auth doctor`

CLI: `jcode auth-test`

Pipeline Progress ?
⚪ not started not yet begun
✏️ draft initial version
🔍 in review under review
🚧 in progress actively worked on
⛔ blocked waiting on dependency
✅ done completed
⏭️ skipped not applicable

CompactionReducing accumulated context (and the KV cache) when a session grows too large. config (`[compaction]`)

Pipeline Progress ?
⚪ not started not yet begun
✏️ draft initial version
🔍 in review under review
🚧 in progress actively worked on
⛔ blocked waiting on dependency
✅ done completed
⏭️ skipped not applicable

CLI: `jcode memory list | search | export | import | stats`

Pipeline Progress ?
⚪ not started not yet begun
✏️ draft initial version
🔍 in review under review
🚧 in progress actively worked on
⛔ blocked waiting on dependency
✅ done completed
⏭️ skipped not applicable

PlanItem / VersionedPlan (`crates/jcode-plan`)

Pipeline Progress ?
⚪ not started not yet begun
✏️ draft initial version
🔍 in review under review
🚧 in progress actively worked on
⛔ blocked waiting on dependency
✅ done completed
⏭️ skipped not applicable