@ligence/continuity

Continuity gives coding agents a hosted work graph: the current goal, the next safe task, the context needed to work, and a place to report what changed.

Install the CLI in any repository where an agent will work:

npm install -g @ligence/continuity

Then save the workspace token from your Continuity workspace:

continuity login --api-token <workspace-token>

login verifies the token and stores it in ~/.continuity/config.json with user-only file permissions. Do not set a workspace ID for normal agent use. The hosted API resolves the workspace from the token.

Start Here

Run setup once in the repository:

continuity setup --json

setup verifies the hosted API, checks your workspace token, installs the version-matched agent instructions at .codex/skills/continuity/SKILL.md, and confirms the graph is ready.

At the start of every agent session, ask Continuity what to do next:

continuity next --agent codex --horizon overnight --compact --json

If the response includes a runnable node, fetch the work packet before editing:

continuity agent-context --node <node-id> --agent codex --json

When the work is finished, blocked, failed, or needs a human decision, report it back:

continuity report-delta \
  --node <node-id> \
  --kind completed \
  --summary "what changed" \
  --evidence "tests passed" \
  --json

What This Package Includes

This package installs the continuity command. It is a small hosted client for agent workflows:

• only bin/continuity, package.json, and this README ship in the package
• no private source checkout
• no local graph database
• no database credentials
• no native graph dependencies
• no workspace secrets bundled in the package

The hosted API is the source of truth for workspace identity, graph state, next-task selection, agent packets, and work-delta reconciliation.

Requirements

• Node.js 18 or newer
• A Continuity workspace token
• Network access to https://api.usecontinuity.dev

Configuration

Use continuity login --api-token <workspace-token> once. login verifies the token and stores the API origin plus bearer token in ~/.continuity/config.json with user-only file permissions. After that, hosted commands read the saved config. Workspace tokens resolve their own workspace at the API; do not set a workspace ID for normal agent use.

If your workspace operator gives you a staging or private API origin, pass it to login once:

continuity login --api-url <hosted-api> --api-token <workspace-token>

For multi-project or multi-repo work, bind each checkout before graph writes:

continuity project bind --json
continuity project status --json

project bind calls the hosted API to create or confirm a project plus repo binding, then writes .continuity/project.json as a local cache of that hosted truth. Hosted graph reads and writes carry the selected project ID. Once that file exists, hosted graph writes (insert, intake, and report-delta) refuse to run if the current repo, API origin, workspace, or project no longer match the binding.

Agent Workflow

A typical agent run should follow this loop:

continuity whoami --json
continuity doctor --json
continuity next --agent codex --horizon overnight --compact --json
continuity agent-context --node <node-id> --agent codex --json
# make the code change
continuity report-delta --node <node-id> --kind completed --summary "..." --evidence "..." --json

Use --json in automation. Structured API errors are printed as JSON and the command exits nonzero, so agents can inspect the returned kind instead of scraping human text.

Commands

Workspace Checks

continuity health --json
continuity whoami --json
continuity version --json
continuity doctor --json

• health checks API reachability.
• whoami verifies the token and workspace identity.
• version reports API, CLI package, and hosted instruction versions.
• doctor runs the full source-free readiness check.

Agent Setup

continuity login --api-token <workspace-token>
continuity setup --json
continuity skills get core
continuity skills install core --json

• login verifies and stores the workspace token in ~/.continuity/config.json.
• logout removes the saved token and API origin from ~/.continuity/config.json.
• setup installs the hosted instructions and checks readiness in one command.
• skills get core prints the hosted agent instructions.
• skills install core writes .codex/skills/continuity/SKILL.md.

Goal Completion

continuity completion-audit --agent codex --json
continuity completion-review --agent codex --json

• completion-audit checks whether the active goal is proved complete and, if not, returns a modeling proposal for the next slice or completion proof. Pass --accept-modeling-proposal to materialize it.
• completion-review reports the current goal-completion review state.

Graph Work

continuity project bind --json
continuity insert --text "Create the next implementation task" --json
continuity next --agent codex --horizon overnight --compact --json
continuity agent-context --node <node-id> --agent codex --json
continuity report-delta --node <node-id> --kind completed --summary "..." --evidence "..." --json

• project bind binds the current git checkout to a hosted project and repo before graph writes.
• insert creates hosted graph work directly. By default it creates a ready, agent-safe task; pass --kind goal, --kind bug, --kind decision, --kind question, --title, --verification, or --supports <goal-id> when needed. ingest is an alias for insert.
• next selects the next runnable work or explains why work is blocked.
• agent-context returns the packet an agent needs before editing. Accepts --task <id> as an alias for --node, so a lane can orient by its $CONTINUITY_TASK_ID.
• report-delta records completed, blocked, failed, learned, or judgment-bound work.

Valid report-delta --kind values:

• completed
• blocked
• failed
• learned
• needs-judgment

Judgment Loop (ask / decide)

When an agent hits a decision the founder should own, it asks instead of guessing. The hosted graph answers from the founder's prior rulings — an instant cache hit, no human — or parks the question for the founder to answer with decide. The next identical ask is then a cache hit, so the founder is never asked the same thing twice.

continuity ask \
  --question "Which datastore for the index?" \
  --task <task-node-id> \
  --qtype design \
  --recommendation "Postgres, we already run it" \
  --options '[{"label":"A","answer":"Postgres","recommended":true},{"label":"B","answer":"SQLite"}]' \
  --wait --json

• ask escalates a judgment call and parks it as a question tied to the task. --wait blocks, re-asking the stateless route until the founder decides; the result is {"status":"answered","source":"cache|human","answer":"..."}. High-stakes --qtype values (irreversible, identity) never match a fuzzy prior ruling — they require an exact prior answer or a human.

continuity decide --node <question-node-id> --choice "Use Postgres" --rationale "We already run it" --json

• decide records the founder's answer on a parked question and archives the deliberation edge, so subsequent matching asks resolve from cache. Use --action answer|accept|defer|block to control how the question is closed.

Intake

continuity intake --text "Capture this observation" --json

intake records raw observations or requests for review. Hosted intake is capture first; it does not directly mutate the work graph.

Feedback

continuity feedback --transcript ~/.codex/sessions/<session>.jsonl --message "What felt broken" --json

feedback sends a bounded, redacted session log to the hosted control-plane event ledger for review and analysis. Large logs are truncated to the recent tail, obvious token/password/API-key patterns are redacted before upload, and the submission returns graphMutation: "none".

Troubleshooting

If setup or doctor fails, keep the JSON output. The kind field is the important part:

• hosted_auth_required: run continuity login --api-token <workspace-token>.
• hosted_auth_invalid: use a valid active workspace token.
• hosted_workspace_forbidden: the token is not allowed to access that workspace.
• hosted_graph_unconfigured: the hosted graph service is not ready yet.
• package or skill mismatch: update the CLI, then run setup again.

Update the CLI with:

npm install -g @ligence/continuity@latest

For Workspace Operators

Operator commands require an admin token and are not needed for normal agent use:

export CONTINUITY_ADMIN_TOKEN=<admin-token>

continuity admin workspaces provision --workspace workspace_123 --label "trial" --json
continuity admin workspaces list --json
continuity admin workspaces get --workspace workspace_123 --json
continuity admin workspace-tokens revoke --workspace workspace_123 --token-id <token-id> --json
continuity admin workspaces deactivate --workspace workspace_123 --json
continuity admin smoke --json

provision --json returns the workspace bearer token once. Store it outside the database and give the user only the token plus the install and setup commands.

Workspace IDs belong to operator/admin lifecycle commands only. End users should not need a workspace ID to install, set up, or run agents.