Skip to main content

Crate synaps_cli

Crate synaps_cli 

Source

Modules§

attachments
Explicit local attachment ingestion. No URL fetches or implicit path expansion in prompts. Bytes are captured once and retained in private session history; archive/memory projections deliberately omit image/document source payloads.
auth
OAuth 2.0 Authorization Code + PKCE flow for Anthropic (Claude Pro/Max).
chain
Chain pointer management — named bookmarks that auto-advance on compaction.
config
core
Core infrastructure — config, session, auth, logging, error types, protocol.
engine
Engine — shared business logic for both TUI and headless modes.
error
events
Event Bus — universal message ingestion for agent sessions.
extensions
Extension system for SynapsCLI.
help
logging
mcp
MCP (Model Context Protocol) integration — JSON-RPC client, tool bridging, lazy loading.
memory
Local-first memory store.
models
Curated list of Claude models known to work with this CLI. Centralized so the settings dropdown, defaults, and subagent hints agree.
orchestration
pricing
Centralised pricing logic for Anthropic models.
protocol
reasoning
Typed named reasoning level — single source of truth across providers.
runtime
session
sidecar
Sidecar plugin support: long-running plugin processes that stream events into the host over a JSONL line protocol.
skills
Skills and plugins subsystem.
toast
Public toast notification primitives for extensions and host UIs.
tools
Tool system — trait, registry, and built-in tool implementations.
tui
Chat TUI binary — event loop, terminal setup, module wiring.
watcher_types

Structs§

AgentConfig
Agent configuration parsed from config.toml
AgentStatusInfo
Runtime info for a single agent (for status display)
BoundedText
Re-export truncate_str + BoundedText from agent-core. A byte-bounded, char-boundary-safe view of a string, with exact accounting of what was kept and what was cut.
CancellationToken
A token which can be used to signal a cancellation request to one or more tasks.
EngineHost
HandoffState
What the agent writes for its next self
Runtime
Session
SessionInfo
Lightweight info for listing sessions without loading full message history
SessionLimits
SessionStats
Stats tracked per agent session
SynapsConfig
Parsed configuration from the config file.
ToolContext
Context passed to tool execution — composition of channels, capabilities, and limits.
ToolRegistry
Registry of available tools. Maintains a name→tool map and a cached JSON schema array that gets sent to the API. Thread-safe via Arc<RwLock<ToolRegistry>>.
TurnError
Typed terminal failure carried by SessionEvent::Error: the human-readable message plus the spec §5.2 TurnOutcome.

Enums§

AgentEvent
BudgetDimension
Budget dimension placeholder (spec §5.2). The full turn-budget system is later work (spec §8.1); only the typed surface lands here so TurnOutcome::BudgetExceeded is representable without re-plumbing.
ExitReason
Why an agent session ended
LlmEvent
RuntimeError
SessionEvent
StreamEvent
Top-level stream event — grouped into concern-specific sub-enums.
TurnOutcome
Typed terminal outcome of a model turn (spec §5.2). Produced ONCE by the engine; every frontend (chat, TUI, RPC, server, watcher, subagents) receives the same value and must never re-derive it from message text.
Value
Represents any valid JSON value.
WatcherCommand
Commands sent from CLI to supervisor
WatcherResponse
Responses from supervisor to CLI

Traits§

Tool
The core trait for all tools. Implement this to add a new tool.

Functions§

epoch_millis
Re-export epoch_millis from agent-core (moved there for the leaf crate split). Current time as Unix epoch milliseconds. Panics only if system clock is before 1970.
epoch_secs
Current time as Unix epoch seconds.
find_session
Find a session by full or partial ID match
find_session_by_name
Find a session by its assigned name (not partial ID). Iterates session headers one file at a time and returns on first match, avoiding a full directory scan when the named session appears early.
flush_stderr
Flush stderr, ignoring errors (pipe closed, etc.)
flush_stdout
Flush stdout, ignoring errors (pipe closed, etc.)
latest_session
Load the most recently updated session
list_recent_sessions
The limit most-recently-modified sessions (by file mtime), most-recent first. Sorts the directory entries by mtime WITHOUT parsing, then reads only the top limit headers — so /sessions is O(limit) reads instead of O(#sessions). mtime is an exact proxy for updated_at (the file is rewritten on every save).
list_sessions
List all sessions, sorted by most recently updated.
load_config
Parse the config file at ~/.synaps-cli/config (or profile variant). Returns default config if file doesn’t exist or can’t be read.
next_turn_correlation_id
Process-unique correlation ID for one engine turn. Ties the typed terminal outcome to metadata-only trace/log lines for the same turn.
resolve_session
Resolve a query string to a Session. Resolution order:
resolve_system_prompt
Resolve the system prompt from CLI flag, config file, or default. Priority: explicit value > ~/.synaps-cli/system.md > built-in default.
truncate_str
Re-export truncate_str + BoundedText from agent-core. Truncate a string to at most max bytes at a valid UTF-8 boundary.
validate_name
Validate a session or chain name: [a-z0-9-]{1,40}.

Type Aliases§

Result
SharedMessage
Reference-counted shared message payload. Introduced at the runtime’s inner boundary (T128 Slice 2) to enable clone-free fan-out of message history through the stream loop and SessionEvent::MessageHistory. Outer state (App/Session/ConversationState) remains Vec<Value> and shims at the boundary — see Slice 5 for full conversion.