The coding agent you can operate.

Jeden is Wisent’s private coding-agent harness. It owns the model loop, policy, tools, terminal interaction, sessions, memory, extensions, and integrations around the model.

The four-part contract

Ways to run Jeden

Where to begin

Start with Getting started. Then read Security model before enabling writes or commands for unattended work.

Getting started

Validate your private preview package, point Jeden at a repository, and complete a first read-only task before granting additional authority.

Prerequisites

• A signed Jeden release supplied through the private preview channel.
• An approved Wisent model entitlement or an operator-provided route through Brama.
• A project directory the current user can read.

Validate the runtime

$ jeden --version

$ jeden doctor --cwd .
$ jeden doctor --json --cwd .

$ jeden capabilities --json --cwd .

BRAMA_URL=<brama-url>
WISENT_APP_AGENT_ID=wisent-app
WISENT_APP_AGENT_AUTH_SECRET=<signing-credential>

$ jeden --cwd ../content-platform

$ jeden run "summarize package.json" --cwd .
$ jeden run "create notes.txt" --cwd . --allow-write

CLI reference

The same runtime serves interactive terminal sessions, one-shot automation, RPC, ACP, and mutually authenticated headless clients.

Global invocation

jeden [--cwd path] [--model name] [--max-tokens n]
      [--allow-write] [--allow-command]
      [--yolo|--auto-approve] [--max-steps n]

Session and runtime commands

Interactive slash commands

Entering a management command without arguments opens a native searchable view where one exists. Direct arguments remain available for automation.

Picker controls

Destructive rows open a confirmation view with Cancel selected by default. When standard input is not a terminal, interactive views render deterministic text lists.

Models & routing

Model selection is separate from policy and execution. Jeden signs OpenAI-compatible requests to Brama and records the route, usage, and billing decision in the session.

Selection precedence

1. The invocation’s --model value.
2. The JEDEN_MODEL environment variable.
3. The model selected through native configuration or /model.
4. The operator-provided default route.

$ jeden --model claude-code-subscription
$ jeden run "review this diff" --model <route>

/model
/model <route>

Authentication ownership

/login [provider] and /logout [provider] inspect or delegate to the entitlement owner. Jeden does not reimplement provider login inside the model loop. /settings shows provider and entitlement state without returning credentials.

Subscription routing

Weles owns subscription state and payment policy. Jeden discovers active subscriptions and quota snapshots, freezes a deterministic order for each logical request, and sends the selected billing target to Brama.

• Request, idempotency, and decision identities remain stable across attempts.
• Typed quota exhaustion places a target into a durable Retry-After-bounded cooldown.
• Failover never occurs after model output becomes visible.
• Served account, subscription, quota bucket, and decision ID are retained in usage and audit events.

Usage controls

/usage
/usage show
/usage reset
/subscriptions list
/subscriptions status

Configuration

Jeden combines operator environment, user preferences, project settings, and discovered instructions without blurring their precedence.

Precedence

1. Environment variables win over file configuration.
2. Project config at <cwd>/.jeden/config.json overrides user config.
3. User config loads from ~/.jeden/config.json and ~/.jeden/config.yml.
4. Built-in defaults apply when no value is supplied.

$ jeden config list --json --cwd .
$ jeden config path --cwd .
$ jeden config get tools.approvalMode
$ jeden config set tools.approvalMode write
$ jeden config reset tools.approvalMode

Native settings

Discovered context

User context loads from ~/.jeden/instructions.md and ~/.jeden/context.md. Project discovery walks ancestors down to --cwd and reads:

A context line such as @./extra.md imports another file under the same context root. Imports remain within that root; oversized files are skipped.

Tools

Jeden exposes typed tools through one capability registry. Every tool has a source, version, health state, policy classification, input schema, output schema, and handler identity.

Discover active tools

$ jeden capabilities --json --cwd .
$ jeden tools --cwd .

/tools

The registry distinguishes executable healthy capabilities from planned or unavailable descriptors. Do not infer availability from a name alone; inspect health.state and ui.executable.

Built-in families

Bounded reads and selectors

Prefer narrow selectors to unbounded output. Text reads support line ranges, comma-separated ranges, raw content, and unresolved conflict views.

src/server.ts:80-140
src/server.ts:10-20,90-110
src/server.ts:raw
src/server.ts:conflicts
artifact://tool-output:1-120
database.sqlite:users:42

Guarded mutations

Existing text files return a digest and snapshot tag when read. A mutation must identify the state it intends to replace. If another actor changes the file first, the write fails instead of overwriting newer work.

• write_file and apply_patch require the expected SHA-256 for existing files.
• The unified writer uses revision guards for files, archives, notebooks, and SQLite.
• Anchored edits use a snapshot path#TAG plus exact visible line anchors.
• Mutations return native diffs and previews.

Sessions & artifacts

A session is the durable record behind an answer: messages, tool calls, results, approvals, usage, artifacts, checkpoints, attachments, and lineage.

Storage

Session transcripts and artifacts live under ~/.jeden/sessions/. Oversized tool results are persisted as artifacts and replaced in the model loop with compact references.

Inspect and recover

$ jeden sessions 20
$ jeden show <session>
$ jeden export <session> output.json
$ jeden artifacts <session>
$ jeden artifact <session> <name> output.bin
$ jeden resume <session> "continue"

Resuming starts a fresh session seeded with selected history; it does not append destructively to the original record.

Interactive lineage

Checkpoints and rewind

/checkpoint before-refactor
/checkpoint list
/rewind <checkpoint-event-id>

A checkpoint records the exact model-visible context. Rewind appends a new active lineage without deleting the abandoned history.

Attachments

/attach path/to/context.txt
/attachments
/detach <id|all>

The attachment tray accepts bounded workspace-jailed text and PNG, JPEG, GIF, or WebP inputs for the next submitted turn.

Memory

Jeden’s durable memory is a local SQLite/FTS index with explicit retrieval and maintenance operations. It is separate from the immutable session transcript.

Storage and overrides

The default database is ~/.jeden/memory.sqlite3. Set JEDEN_MEMORY_DB to select another database. The legacy JEDEN_MEMORY_FILE remains an input-path override.

Operations

/memory stats
/memory view
/memory enqueue
/memory queue
/memory queue run
/memory queue drain
/memory rebuild
/memory clear

What memory is not

• It is not a substitute for project instructions or source-controlled context.
• It does not erase or rewrite the session ledger.
• Retrieved content remains subject to the current prompt budget and policy.
• Maintenance commands do not silently grant tool authority.

Roadmap registry

A repository can carry a typed, versioned roadmap that the agent and team mutate through the same atomic contract.

Canonical files

roadmap/roadmap.yaml is canonical. roadmap/schema/roadmap-v1.schema.json defines the machine contract. Human views are deterministic generated outputs.

Mutation guarantees

• Every operation uses a stable sibling lock.
• expectedRevision detects concurrent updates.
• Writes use a same-directory temporary file, flush, fsync, atomic rename, and parent-directory fsync.
• Dependencies must resolve and remain acyclic.
• passed requires evidence; external_blocked requires an external prerequisite.

Core commands

$ jeden roadmap list --status planned --priority P1 --json
$ jeden roadmap show JED-024 --json
$ jeden roadmap graph --json
$ jeden roadmap check --json
$ jeden roadmap render
$ jeden roadmap work JED-024 --cwd .

State transitions

roadmap work sets the active goal and plan, creates todos from acceptance criteria, records a start event in the current session, and pins subsequent artifacts and branches to the roadmap item.

Model Context Protocol

Jeden maintains bounded persistent MCP connections and exposes server tools, resources, prompts, notifications, and health through native commands.

Configuration

User servers load from ~/.jeden/mcp.json. Project servers load from <cwd>/.jeden/mcp.json. Both use the standard mcpServers shape.

{
  "mcpServers": {
    "example": {
      "command": "/absolute/path/to/server",
      "args": ["--stdio"]
    }
  }
}

Operate servers

/mcp
/mcp list
/mcp tools
/mcp resources
/mcp prompts
/mcp notifications
/mcp test
/mcp reload
/mcp reconnect

Tool naming

Generic MCP tools can list and call every configured server. Eligible tools may also be projected into the native registry as mcp__<server>__<tool>. Names remain unique and capability health reflects the current server connection.

Installation & updates

Jeden is distributed as a signed private-preview release. Treat the binary, its trust roots, and its release evidence as one unit.

Requirements

• A supported signed artifact supplied through the Wisent preview channel.
• Access to the model and entitlement endpoints selected by your operator.
• A writable home directory for configuration, sessions, memory, plugins, and update state.

Verify an installation

$ jeden --version
$ jeden doctor --json --cwd .
$ jeden conformance --json --cwd .

Do not infer health from a successful process launch. Diagnostics confirm storage, policy, providers, capability registration, and workspace-specific dependencies.

Update and rebuild

/update enters the signed update flow. /rebuild rebuilds the local checkout and resumes the active session. Stable promotion remains operator-controlled; canary identities include the CI run, attempt, and tested commit.

Using Jeden

A reliable run has four explicit inputs: workspace, objective, authority, and verification.

Choose the workspace

--cwd establishes the project root used by context discovery and workspace-jailed tools. Start Jeden at the narrowest directory that contains the task.

State the observable outcome

Name the behavior to change, constraints that must remain true, and the command or scenario that proves completion. Put durable project rules in JEDEN.md or AGENTS.md; keep one-off instructions in the prompt.

Grant only required authority

Review the evidence

Read the final answer together with the session’s tool results, artifacts, usage, and approval events. A confident statement is not a substitute for an executed verification path.

Interactive terminal

Running jeden opens the native terminal interface: conversation, composer, status line, searchable management views, approvals, and streamed tool state.

Launch

$ jeden --cwd .
$ jeden --cwd . --model <route> --allow-write

Composer

Enter submits a prompt; the attachment tray supplies bounded text or image inputs to the next turn. Slash commands act on runtime state without being sent as ordinary user prose.

Native views

Authentication, models, settings, approvals, sessions, todos, modes, tools, MCP, SSH, usage, memory, browser state, collaboration, jobs, extensions, plugins, and marketplaces expose searchable pickers. A selected row dispatches the same validated command available by direct entry.

Confirmations

Destructive views open with Cancel selected. Non-interactive standard input renders deterministic text instead of waiting for terminal controls.

One-shot runs

jeden run executes one objective without opening the long-lived interactive terminal.

Usage

$ jeden run "summarize the API surface" --cwd .
$ jeden run "update the version" --cwd . --allow-write
$ jeden run "inspect failures" --cwd . --json

Bounds

--max-steps limits model/tool iterations and --max-tokens bounds each model response. The workspace, model, write exposure, command exposure, and approval flags have the same meaning as interactive mode.

Model-only mode

--model-only suppresses tool execution for tasks that must produce an answer solely from supplied context. It is not a substitute for filesystem isolation when sensitive data is present.

Automation contract

Use --json when another program consumes the result. Inspect the terminal status and retained session rather than treating process success as proof that a requested code change passed verification.

Run modes

Modes alter how Jeden organizes work; they do not silently grant filesystem, command, or network authority.

Plan mode

/plan on makes the active plan explicit. /plan-review opens review of the current plan. Use it for multi-step work where dependencies and acceptance criteria matter.

Goal and loop

/goal set records the outcome carried across turns. /loop on enables continuation while open work remains; /goal done or /goal drop closes it.

Fast and advisor

/fast selects the latency-oriented operating profile. /advisor selects an advisory posture. The active model route, policy, and capability registry remain independently inspectable.

/plan status
/goal set Stabilize the import path
/loop status
/fast
/advisor

Slash commands

Slash commands control the local harness. They are parsed before ordinary prompts and are not treated as model-authored tool requests.

Accounts and models

Work and state

Session lifecycle

Runtime and extensions

Run /help for the current registry-derived command list. Availability and exact subcommands may depend on active capabilities and operator policy.

Hotkeys & pickers

Keyboard behavior is discoverable at runtime through /hotkeys; searchable views share a consistent control model.

Picker controls

Safety behavior

Rows that mutate or delete state route through a confirmation view. Cancellation is the initial selection. Filtering a list never executes a row.

Current bindings

Use /hotkeys rather than relying on a hard-coded copy when terminal integrations or active extensions can alter available actions.

Approvals

Exposure determines what the model can propose. Approval determines which exposed effects may execute.

Modes

Inspect and change

/approval status
/approval mode
/approval set write
/approval reset

The persistent default is tools.approvalMode. Invocation flags may select a run-specific posture without editing project configuration.

Decision order

1. Capability must be healthy and exposed.
2. Input must satisfy schema and workspace policy.
3. Pre-tool hooks may narrow or block the call.
4. Approval policy decides whether operator confirmation is required.
5. The result and decision are appended to the session.

Authentication

Jeden does not embed provider credentials into prompts or duplicate provider login logic. Authentication is delegated to the configured entitlement owner.

Inspect status

/settings
/login
/login <provider>

Status views report provider and entitlement state in redacted form. They do not print tokens, cookies, or stored credentials.

Lifecycle

/login <provider>
/refresh <provider>
/logout <provider>

The entitlement router owns whether a provider supports native login, a browser handoff, a device flow, or operator-managed credentials.

Operator configuration

ENTITLEMENTS_ROUTER_BIN overrides the executable used by authentication operations. The binary boundary allows Jeden to inspect and request actions without taking ownership of secret storage.

Billing & usage

Weles owns subscriptions and payment policy. Jeden records model usage and selects only eligible billing targets returned by that control plane.

Payment boundary

/payment-method setup --account <id> opens a Weles-hosted HTTPS setup flow. Jeden never accepts or stores card numbers, CVC/CVV values, processor tokens, billing addresses, or payment credentials.

Purchase policy

/billing policy get
/billing policy set … --approve
/billing policy reset
/subscriptions list
/subscriptions status

Automatic purchase and renewal remain disabled until an explicit revision-pinned policy is enabled. Financial mutations require caller idempotency and are checked against pinned policy and quote revisions.

Quota and failover

For each logical model request, Jeden freezes an eligible subscription order. Typed quota exhaustion moves a target into a durable Retry-After-bounded cooldown. Failover does not occur after output becomes visible.

Usage ledger

/usage show reports token and cost accounting; /usage reset resets the local view. The served account, subscription, quota bucket, and route decision remain attached to session audit data.

Environment variables

Environment values override file configuration. Supply secrets through the operator’s secret store, not through source-controlled files.

Model routing

Control planes

Storage

Inspect safely

jeden doctor --json reports whether required values are configured without printing their contents. Secret discovery protects values from secret-named environment variables before model-bound text is built.

Context & rules

Context is explicit project guidance loaded before the user task. It is distinct from memory, conversation history, and tool output.

Discovery

User sources are ~/.jeden/instructions.md and ~/.jeden/context.md. Project discovery walks from the project ancestor down to --cwd and reads JEDEN.md, AGENTS.md, CLAUDE.md, RULES.md, .jeden/instructions.md, and .jeden/context.md.

Imports

A line such as @./extra.md imports a file below the same context root. Absolute escapes and parent traversal outside that root are rejected. Oversized files are skipped rather than silently truncated into misleading rules.

Budgets

Inspect active context

Use /context to inspect the sources selected for the current workspace. Keep build commands, architectural boundaries, and verification requirements source-controlled; keep credentials out.

Secrets

Secret protection reduces accidental exposure to a model. It does not turn source files, prompts, or transcripts into a secret store.

Settings

Boundary

• Never commit credentials to project configuration or context files.
• Do not paste private keys, session cookies, or access tokens into prompts.
• Use the platform secret store for operator and control-plane credentials.
• Review exported sessions before sharing them outside the trusted boundary.

Limitations

Automatic discovery depends on known values and secret-like names. It cannot reliably classify every sensitive business value. Workspace and network isolation remain necessary for high-risk data.

Capability registry

The registry is the source of truth for what this process can expose and execute. UI lists and protocol surfaces are projections, not independent feature declarations.

Inspect

$ jeden capabilities --json --cwd .
$ jeden doctor --json --cwd .
$ jeden conformance --json --cwd .

Descriptor contract

Each descriptor identifies its stable ID, kind, source, version, operations, provenance, dependencies, health, policy, UI affordance, target, schemas, handler, grants, generation, and health evidence.

Availability

A visible label is not enough. A callable capability must have a healthy state, executable UI projection, registered handler, compatible schema, and effective grant. In-flight operations pin the generation they began with.

Kinds

Files & structured data

Filesystem and structured-data tools share workspace jails, bounded output, and stale-state protection.

Read families

read routes text selectors, binary files, images, archives, documents, notebooks, SQLite rows, artifacts, MCP resources, and HTTP(S) content. Narrow operations remain available as read_file, read_image, read_archive, read_document, and read_sqlite.

Discovery and search

Discover paths before reading unknown files. Prefer bounded selectors and native search over shell traversal.

Mutations

write, write_file, archive and SQLite writers, patches, anchored edits, moves, and deletes require write exposure. Existing state is guarded by a digest or snapshot tag so concurrent changes fail instead of being overwritten.

Addressing

src/lib.rs:40-90
src/lib.rs:raw
archive.zip:path/in/archive
state.sqlite:jobs:42
artifact://large-output:1-120

Processes & evaluation

Process tools require command exposure and remain subject to approval, cancellation, deadlines, output limits, and session evidence.

Choose the narrowest operation

Long-lived and interactive work

pty_session and pty_resize manage terminal processes that need later input. Background jobs must remain addressable by a stable handle; do not orphan servers or watchers.

Output and cancellation

Large output spills to an artifact reference. Cancellation applies to the tracked process tree, not just a parent PID. Timeouts and terminal status are retained in the session.

Git & GitHub

Jeden separates read-only repository inspection from mutations that publish or rewrite shared state.

Local Git

Use typed history and diff tools before shelling out. Guarded push requires explicit authority and verifies the intended repository state.

GitHub

Issue and pull-request tools operate on typed repository resources. Search locates code and discussions; Actions inspection exposes workflow state without conflating it with local process output.

Shared-state rule

Do not overwrite unexpected local changes or rewrite a branch you do not own. Read current status and references immediately before any shared-state mutation.

Code intelligence

Structured code tools reason about syntax and runtime state instead of treating source as undifferentiated text.

AST search and rewrite

ast_search finds syntax-shaped matches with metavariables. ast_rewrite applies one-language structural transformations where text replacement would confuse shadowing, formatting, or nested syntax.

Debug sessions

debug_session owns debugger lifecycle. debug_request performs breakpoints, stepping, stack inspection, scopes, variables, evaluation, and supported memory operations through the active adapter.

Choose by invariant

Browser & web

Use direct fetch for static content and browser automation only when navigation, JavaScript, authentication, or interaction requires a real page.

HTTP reads

fetch_url returns the requested response. fetch_readable_url extracts bounded reader-oriented content. Network output remains subject to size limits and artifact spill.

Tabs and actions

Tabs have stable handles. Actions navigate, observe, select, click, type, scroll, extract, and wait against the current document state. Navigation invalidates stale element references.

Visible and headless

/browser status
/browser headless
/browser visible

Visible mode is appropriate when an operator must observe or complete an authentication step. Screenshots verify appearance; accessibility or DOM extraction verifies structure and state.

Images, audio & documents

Media tools preserve the distinction between visual inspection, generated assets, document extraction, and audio output.

Images

Inspection grounds claims about an existing image. Generation creates a new asset from an explicit subject and composition. Editing requires an input image and named changes.

Documents and archives

read_document extracts supported office, PDF, and notebook content. read_archive addresses members without unpacking an entire archive into the workspace.

Audio

tts produces speech output where enabled. Generated media is retained as a file or session artifact rather than inlining unbounded binary data into the model loop.

Prompt attachments

The terminal attachment tray accepts bounded workspace-jailed text plus PNG, JPEG, GIF, and WebP files for the next submitted turn.

Tasks & delegation

Coordination tools turn multi-step work into explicit state without transferring authority implicitly.

Todos

todo and /todo track named tasks and completion state. A todo records intent; it is not evidence that implementation or verification happened.

Operator decisions

ask_user requests input only when materially different choices require the operator. Questions and answers remain in the session lineage.

Subagents

delegate_task assigns a self-contained slice to an available agent. Use /agents to inspect the current roster and capability state. Delegated work returns evidence and artifacts to the parent session.

Authority

A delegate receives only the grants, workspace, and interfaces provided by the parent runtime. It does not inherit external credentials or approval bypass merely because the parent requested work.

SSH & remote work

Remote work is a separate authority boundary. Host identity, authentication, path scope, and command exposure must all be explicit.

Remote tools

Read and search operations inspect configured hosts. Writes and command execution require the corresponding local capability exposure and approval.

Connections

/ssh opens the native SSH configuration and status view. It reports available connection identities without printing private key material.

Host identity

Use pinned known-hosts data for unattended work. Do not disable host-key verification to make an automation path pass. Scope remote identities to the exact command or filesystem surface they need.

Evidence

Remote requests, terminal status, bounded output, and artifacts remain attached to the local session. A remote mutation should be followed by a remote read or service-level smoke check.

Session tree

Conversation history is a graph of durable lineage, not one mutable transcript.

Lineage operations

Organization

/rename changes a session label. /move <dir> changes its organizational location. /drop removes the active session from the normal working set through a confirmed operation.

Invariant

Branching, resume, and rewind append new lineage. They do not edit prior model messages, tool results, approvals, or usage events in place.

Checkpoints & rewind

Checkpoints name a recoverable context boundary inside a durable session.

Create and inspect

/checkpoint before-refactor
/checkpoint list

The checkpoint event records the exact model-visible context, not merely a human label or source-control commit.

Rewind

/rewind <checkpoint-event-id>

Rewind appends a new active lineage from the selected checkpoint. The abandoned continuation remains available for audit and comparison.

Source files

A session rewind does not automatically revert the workspace. Use Git or guarded file mutations when source state must also move back, and verify that the chosen source revision matches the checkpoint’s assumptions.

Compaction & handoff

Long sessions need bounded model context without discarding the durable event history.

Compaction

/compact
/compact focus on the failing import path

Compaction summarizes the active model context. The original messages and tool events remain in the session ledger.

Handoff

/handoff
/handoff focus on release verification

A handoff packages current state, decisions, unresolved work, and evidence so another continuation can resume with a bounded focus.

Choose correctly

Artifacts & attachments

Artifacts are durable session outputs. Attachments are bounded inputs consumed by a prompt.

Artifact recovery

$ jeden artifacts <session>
$ jeden artifact <session> <name> output.bin
$ jeden export <session> output.json

Oversized tool results spill to the artifact store and are represented in model context by bounded artifact:// references.

Attachment tray

/attach path/to/context.txt
/attachments
/detach <id|all>

Accepted inputs are bounded workspace-jailed text and supported PNG, JPEG, GIF, or WebP images.

Export and share

/export produces JSON or text session output. /dump renders diagnostic session content. /share creates the configured sharing representation. Review secrets and proprietary data before moving any export outside the trust boundary.

Collaboration & jobs

Collaboration synchronizes explicit session state. Jobs expose tracked work that outlives a single foreground tool call.

Collaboration lifecycle

/collab status
/collab start
/collab share
/collab sync
/join <relay-file-url-or-path>
/leave
/collab stop

A relay reference conveys connection information, not blanket local tool authority. Joined peers remain represented as session events.

Jobs

/jobs opens the native tracked-job view. Use it to inspect ownership, state, progress, terminal outcome, and retained output instead of searching for unverified process IDs.

Failure behavior

Disconnects do not rewrite prior collaboration events. A stopped or failed job retains its outcome; restarting work creates a new attempt or explicit continuation.

Custom commands

File-based commands package repeatable prompts and local workflows without forking the Jeden runtime.

Locations

Compatibility settings

commands.enableClaudeUser, commands.enableClaudeProject, commands.enableOpencodeUser, and commands.enableOpencodeProject enable their corresponding loaders. All default to true.

Discovery

Use /help to inspect active commands and /extensions to inspect extension sources. Names must not silently shadow a native command with a different authority contract.

Hooks

Hooks run at documented lifecycle boundaries and return bounded decisions to the same policy engine used by native operations.

Events

Allowed decisions

A hook may add context, replace documented input fields, or block an operation. A hook cannot grant a capability that is absent, unhealthy, outside the workspace jail, or forbidden by operator policy.

Operate

/hooks inspects active hook sources and status. Hook output should be deterministic, bounded, non-interactive, and free of secret material.

Failure contract

A required policy hook that cannot produce a valid decision must fail closed. Post-tool failures are retained as evidence and must not erase the underlying tool result.

Custom tools

Custom modules add typed operations to the capability registry without bypassing native execution policy.

Locations

User modules load from ~/.jeden/tools/; project modules load from <cwd>/.jeden/tools/. Each module exports a default factory.

Factory contract

The factory receives current workspace helpers and returns one tool or a list of tools. Each tool declares a unique name, description, input contract, and executable handler.

Policy

• Names cannot collide with built-in or already active tools.
• Filesystem access remains workspace-jailed.
• Write and command classifications still require exposure and approval.
• Pre-tool and post-tool hooks apply.
• Health and handler identity appear in the capability registry.

Inspect

$ jeden tools --cwd .
$ jeden capabilities --json --cwd .

Plugins & marketplaces

Marketplaces discover packages; plugins are installed and activated extension units. Their state lives under ~/.jeden/plugins/.

Marketplace operations

/marketplace list
/marketplace discover
/marketplace installed
/marketplace add <source>
/marketplace remove <name>
/marketplace install <name>
/marketplace uninstall <name>
/marketplace upgrade <name>

Plugin state

/plugins list
/plugins enable <name>
/plugins disable <name>
/reload-plugins

Reload creates a new capability generation. Existing operations finish against the generation they started with.

Other extension sources

/extensions lists native project and user extensions. /agents lists available agent definitions. Installed status alone does not imply executable health; inspect the capability registry after activation.

RPC & ACP

Protocol modes adapt the same session lifecycle and capability registry used by the interactive terminal.

NDJSON RPC

$ jeden rpc

RPC serves newline-delimited JSON requests and events over standard input and output. Keep diagnostic logging off the protocol stream.

Agent Client Protocol

$ jeden acp

ACP exposes the runtime through the Agent Client Protocol on standard I/O for compatible editors and hosts.

Shared invariants

• Requests use the same workspace and policy gates as local sessions.
• Capabilities come from the active registry generation.
• Tool calls, approvals, usage, artifacts, and terminal outcomes are durable session events.
• Cancellation and deadlines are operation-scoped.

Headless mTLS

Headless mode exposes Jeden to authenticated clients without weakening local capability and approval policy.

Usage

$ jeden headless <addr> \
  <server-cert.pem> <server-key.pem> \
  <client-ca.pem> <identity-map.json> \
  [revoked-serials.txt]

Identity

The server certificate authenticates the service. The client CA authenticates client certificates. The identity map converts a certificate identity into an explicit Jeden principal; unknown identities are rejected.

Revocation

The optional serial list denies known client certificates even when their chain remains valid. Keep it readable by the service and update it atomically.

Local policy remains authoritative

Mutual TLS authenticates transport and caller. It does not grant write, command, browser, SSH, plugin, or MCP authority by itself. Those decisions remain local and auditable.

Diagnostics

Diagnostics answer why a capability is unavailable or a run is unhealthy without printing protected credentials.

Doctor

$ jeden doctor --cwd .
$ jeden doctor --json --cwd .

Doctor evaluates workspace storage, configuration, provider prerequisites, extension sources, and runtime dependencies.

Conformance

$ jeden conformance --json --cwd .
$ jeden capabilities --json --cwd .

Conformance checks registry invariants and public contracts. Capability output supplies descriptor-level health and evidence.

Interactive status

Report with evidence

Include the Jeden version, operating mode, affected capability ID, health state, terminal error, and smallest reproduction. Redact endpoint credentials, tokens, cookies, private keys, and session exports before sharing.

Security model

Jeden treats model output as a proposal. Authority comes from the local runtime, its operator policy, and the exact state observed before an effect.

Defense layers

Approval modes

Model-bound secrets

Known secrets are protected before text reaches the model. secrets.mode selects redaction or obfuscation. Environment discovery protects secret-named variables at or above secrets.minLength.

Remote runtimes

jeden headless requires a server certificate, server private key, client CA, explicit identity map, and optional revoked-serial list. Mutual TLS authenticates the transport; the local tool policy still governs effects.

Action protocol

Native provider tool calls and strict JSON actions enter the same validated local execution loop. Tool schemas are derived from each input contract and sent with the model request.

Execution loop

1. The model returns a native tool call or a strict JSON action.
2. Jeden resolves the action against the current capability registry.
3. Input schema, path jail, exposure flags, approval mode, and hooks are evaluated.
4. The handler executes and returns a typed result.
5. The result is appended to the session and returned to the model.
6. The loop continues until a final answer or configured step limit.

Action shapes

Actions are explicit objects; prose that resembles a command does not execute. A strict action identifies the action name and its typed arguments. Selectors and mutation guards are carried as data, not inferred from surrounding text.

{
  "action": "read_file",
  "args": {
    "path": "src/server.ts:80-140"
  }
}

Selectors

Anchored edits

An anchored edit names the snapshot tag returned by the latest read, then applies tight line or block operations only to visible anchors. Every successful mutation produces a fresh snapshot; subsequent edits must re-read or use the new tag.

• SWAP replaces an exact visible line range.
• INS.PRE / INS.POST inserts without restating unchanged lines.
• DEL deletes an exact line range.
• Block operations target a complete syntax block at its opener.
• MV / REM move or remove a file under the same guarded contract.

Oversized results

Large tool output is persisted under the session artifact store. The model receives a compact artifact:// reference and may issue bounded follow-up reads instead of carrying the full payload in context.