Cue

Cue is a durable local execution kernel for work shared by people and agents. Clients submit a fully typed ExecutionSpec; cued owns process groups, PTYs, output, execution facts, idempotency, and restart recovery.

Cue deliberately does not own session cursors, schedules, automatic retry, resource policy, approvals, remote fleets, or a general DAG. Those systems may submit ordinary executions, but cannot extend the closed execution algebra.

Quick start

Install the Python distribution (the command names remain Cue):

uv tool install cue-run

Start the local daemon, then continue in the same terminal:

cued start

cue client exec "printf hello"
cue client list
printf 'echo hello from cue\n' > hello.cue
cue run hello.cue
cue tui
cue daemon status

cued start runs in the background and returns only after that new instance answers IPC v4 Hello. Logs are appended to <socket>.log; the startup command prints the path and reports child startup errors. Use cued start --fg (or -f) for foreground logs or a service manager. cued stop waits for shutdown and cued restart waits for the requested replacement to become ready.

The installed commands are cue, cue-client, cue-tui, and cued. CUE_SOCKET selects a non-default local Unix socket. Remote transport, named targets, and service management are external wrappers rather than daemon state.

Execution semantics

ExecutionPlan has exactly four variants:

• Builtin: cd, env set|unset, or umask;
• Run: one typed process pipeline and its captured-or-PTY I/O mode;
• Sequence: run the second plan on success, failure, or always;
• Parallel: join all branches or finish after any branch succeeds.

Builtin and Run leaves receive stable StepId values such as E7/S2. Sequence threads the resulting Scope; Parallel forks one input Scope into every branch and never merges branch mutations.

The frontend language is direct argv, not an implicit shell:

RUST_LOG=debug cargo test
printf hello |> wc -c
cargo fmt -> cargo clippy
cargo test || cargo test --doc
cargo test ||| cargo test --doc
cd crates/cue-core -> cargo test
env set MODE=release -> printenv MODE

A=B command patches only that process. In A=B left |> right, the right process does not inherit A. command A=B keeps A=B as a literal argument, and an assignment without an executable is rejected. Use the env builtin to change the Scope seen by later sequence steps.

Operators map as follows:

IPC v4 and persistence

IPC v4 uses strict length-prefixed JSON on a private Unix socket. Every connection begins with Hello; read-only Queries use RequestId, while every side-effecting Command also carries an idempotent OperationId. The protocol contains explicit Scope, Execution, output, PTY attachment, and daemon lifecycle operations—no raw source or ambient session handshake.

The default database is $XDG_DATA_HOME/cue/cued-v4.db (or the corresponding XDG fallback). Each running daemon exclusively owns its socket and database; use a distinct --db PATH for an independent instance with another socket. A legacy cued.db is renamed to a read-only cued-v3-<timestamp>.db.archive with its sidecars. Cue does not import or dual-read incompatible v3 semantics. Environment values carry explicit sensitivity; this host rejects Sensitive values before persistence. Variable names never determine classification. An uncertain physical Run after a crash blocks recovery instead of replaying it or inventing completion.

CLI

cue-client run FILE.cue
cue-client exec SOURCE
cue-client list
cue-client show|wait E7
cue-client out|err|terminal E7/S2
cue-client cancel|kill E7
cue-client fg E7/S2 [--observe]
cue-client restart|shutdown

cue run and cue fg are shortcuts. exec and run wait for completion, then print retained output and return the execution exit status. Spawn, builtin, and runtime failures include a Step ID and diagnostic on stderr. They currently do not stream output or forward stdin during that wait. To run an interactive program, submit it in cue tui, press F3 and f to attach its selected PTY Step, or use cue fg E7/S2 in another terminal. PTY control uses one controller and any number of observers; Ctrl-] detaches the controller CLI. Disconnecting the client does not cancel its work; use list/show to find it and cancel/kill to stop it.

cue tui opens an execution sidebar and follows the selected Step's output without requiring an :out command. F2 focuses the sidebar; F3 focuses output; F4 returns to command input. With output focused, 1–6 select combined output, stdout, stderr, terminal, details, or activity. Use [ / ] to change Steps, PgUp/PgDn to scroll, and End to follow live output again. Delete cancels the selected execution, K force-cancels, and f / o attach / observe a PTY. Ctrl-] returns from PTY interaction to the workbench. F1 shows all shortcuts.

Tab completes input, ↑/↓ recall command history, and bracketed paste inserts multiline source for review before Enter submits it. Ctrl-Y copies the active view when the terminal supports OSC 52. Ctrl-B toggles the sidebar; narrow terminals show it when F2 is focused. A disconnected daemon leaves the last snapshot and input draft visible while the TUI reconnects automatically. Pending commands are never automatically resubmitted. Command history is stored under $XDG_DATA_HOME/cue (or ~/.local/share/cue).

The bundled output store retains only the last 1 MiB per Step stream in memory. exec, run, and stream reads warn when the requested prefix has been evicted. All output bytes are lost on daemon restart even though execution history and output-range facts remain. These commands are not a complete log archive. An abrupt crash with an unresolved Run attempt can block startup; there is no supported abandon/repair command yet. See recovery limits.

Cue passes $VAR and ~ literally when they reach Cue source; it does not perform shell expansion. Changes through cd/env/umask apply only within one composed execution, not to the invoking shell or the next TUI submission.

Repository structure

• cue-core: root execution ADT, Scope, reducer, facts, and identities;
• cue-protocol: strict IPC v4 messages and framing;
• cue-store-sqlite: Scope/Execution/fact/operation persistence provider;
• cue-runtime: bootstrap Composition, typed providers, runner, and recovery;
• cue-language: surface tokenizer, parser, compiler, completion, highlighting;
• cue-daemon: composition root, IPC service, lifecycle, and local host;
• cue-client: explicit Scope submission and sequential/multiplexed clients;
• cue-tui: execution browser, live output, and interactive PTY workbench;
• cue-cli: installed command aggregator and extension dispatch.

Development gates:

Changes to Cue's public contracts start with a numbered Feature Proposal. Candidate proposals live directly in fps/; there is no separate drafts directory.

just check
just test
just msrv
just package-smoke
just npm-package-smoke

Repository guidance: 协作约定、愿景、 设计原则、贡献指南。

See architecture, design, testing, and the canonical agent Skill.

Recovering after a daemon upgrade

Replacing the cued executable does not replace an already running daemon. If status, stop, or restart reports that the socket is listening but the IPC v4 handshake failed, stop the old process independently of its protocol:

cued stop --force
cued start

Use the same --socket PATH for both commands when using a custom socket. stop --force sends SIGTERM to the same-user process identified by the socket's kernel peer credentials and waits up to fifteen seconds for exit. It does not send SIGKILL, delete sockets, or use PID files. A timeout is a failed stop, not a success; if a service manager restarts the process, stop that service first. Normal v4 shutdown still drains owned Runs when receiving SIGTERM. cued start returns after background readiness. A service manager should run cued start --fg and own its restart policy. When restarting a custom database, also pass the original --db PATH to start. The first default v4 start archives cued.db and creates cued-v4.db; old sessions and execution history are not imported.