Help operators and developers use Sediment

Use this guide when you help an operator run Sediment or help a developer capture work from repositories and coding agents. Both roles install the Sediment CLI. Developers connecting to a shared server use the installer’s --capture-only option; they don’t need to run a local server. sediment guide prints this bundled guide without reading configuration, contacting a server, or changing the machine. It converts procedure links to raw GitHub URLs pinned to the release it ships in, or to main from a source checkout. Reading those pages requires network access. sediment --help lists public commands; hooks invoke others.

​

Read the state before changing it

• Run sediment --version. For a shared deployment, compare it with the server’s /health version. Use the guide from the version you operate.
• Establish the task, server URL, deployment method, server account, and repository. A developer’s machine might only send capture to a remote server.
• Use /health to check server readiness and sediment doctor <repo> to inspect capture. Neither proves that the server received agent evidence.
• Stay within the requested task. Don’t start another server, reinstall hooks, upgrade, rotate credentials, quarantine Facts, or remove data as a repair unless that change is authorized. Follow the linked procedure for changes.

​

Help an operator

Run server commands as the account that owns the deployment. For database commands, first set up the operator shell from the deployment procedure. An API login doesn’t configure database access. Keep operator credentials on the operator machine; give developers capture credentials only. sediment server runs in the foreground. Without an external PostgreSQL connection, it downloads PostgreSQL on first use and owns the local database. It stores data, credentials, and mirrors under ~/.sediment/server or --root. Starting it provisions database roles and applies migrations. Preserve that directory across restarts and upgrades. Plan backups before migrations or teardown. Use the deployment’s supervisor to manage a shared server.

​

Help a developer

Use the server URL and capture credential that the operator supplies. Login saves credentials; installation changes Git hooks, agent configuration, and shell configuration. Run these steps when the developer requests capture. Default doctor checks configuration and contacts the server and origin. It changes nothing unless you pass --fetch, which updates a notes tracking ref. Only FAIL lines make it exit 1. A sandbox network restriction or an unloaded capture environment can explain a failure. Use the agent procedure’s Session checks to verify delivery. commit requires an operator credential; no attributions before the push and notes reach the server isn’t a failure.

​

Preserve capture while doing repository work

• Leave the marked sediment-attribution Git hook blocks, notes.rewriteRef, and refs/notes/sediment in place. Don’t bypass hooks or change core.hooksPath. If hook files are tracked, leave Sediment’s uncommitted blocks for the developer; don’t commit, stash, or revert them incidentally.
• Keep the sediment executable at its installed path. Hooks use that absolute path; source installs also depend on their checkout and virtual environment.
• Preserve the sediment env blocks in shell profiles and Sediment’s entries in Claude Code settings, Codex hooks and profiles, Cursor hooks, and pi settings. User-level agent hooks apply across repositories.
• Read hook output. Sediment commands end in || true, so they never fail a commit or push. The marked block keeps the hook’s previous exit status. Commands after the block still run. A zero status alone doesn’t prove that capture succeeded.

What the installer changes describes the hooks. Roll out managed capture covers system settings, gateways, and fleet installation.

​

Remove capture within its installation scope

• uninstall <repo> removes that repository’s hook blocks and Sediment’s notes.rewriteRef value. Require removed git hooks from in its output; a silent exit can mean that the path isn’t a Git repository.
• uninstall <repo> --agents also removes user-level agent hooks, including pi, environment files, shell blocks, and verified Codex telemetry blocks. These user-level removals affect capture across repositories. The command doesn’t remove Claude Code managed settings, fleet Git templates, or externally distributed environment settings. Follow Remove managed capture for those installations. Report skipped files; don’t claim complete removal.
• logout removes stored CLI credentials, but environment files retain their ingest token and hooks keep running. It doesn’t stop capture.
• Neither uninstall form removes existing notes, remote notes, or ~/.sediment/. An auto_install_remotes allowlist can reinstall hooks at the next Session. Remove that entry as part of an authorized teardown. Restart running agents so they stop using the earlier environment.

​

Keep credentials and captured content private

Don’t print credentials, paste them into chat, or commit them. Credential locations include ~/.sediment/config.json, ~/.sediment/env.sh, the Fish sediment.fish file, Codex telemetry profiles, and server environment files. Custom server roots, shell profiles, and service settings can hold them too. Don’t dump the process environment: it can contain SEDIMENT_INGEST_TOKEN, OTEL_EXPORTER_OTLP_HEADERS, database passwords, and gateway credentials. Follow Secure a deployment when handling secrets. Capture can leave the developer machine in these forms:

• The pre-push hook sends the whole notes ref to origin only, even during git push --dry-run. A push to any other remote, such as a fork, sends and fetches no notes. Notes contain commit SHAs, agent names, Session identifiers, and timestamps, including other branches’ notes. They don’t contain prompts, diffs, file paths, model names, or hostnames.
• Agent telemetry goes to the Sediment server. Claude Code tool details can include paths, shell commands, edit text, and the Claude account email. Codex decisions can include patch code and tool arguments; Sediment removes the Codex account email and account identifier before storage. Cursor sends accept decisions for applied writes and a configured user identifier.
• Opt-in transcript capture sends edit text and edited-file contents. Claude Code transcripts also include refused edit text and non-agent change counts.
• If the operator routes model calls through a gateway, it captures full prompts and responses.

Privacy boundaries and ceilings describes these payloads and their limits.