Run your first connected session

Take a repository from "nothing installed" to a Claude Code or Codex session whose work is recorded in Jentrix: every session binds to one confirmed project, captures its observable path as redacted TRACE artifacts, and ends with a deterministic RUN_SUMMARY on the project's Runs tab. Reference contract: CLI guide → Connected sessions.

Prerequisites

Node.js ≥ 20 and a git checkout of the repository you'll work in.
A Jentrix account that is a member of the target workspace.
The provider you plan to drive, signed in on this machine: Claude Code (claude on PATH, authenticated) and/or Codex CLI (codex login, runs on a ChatGPT subscription). Jentrix never automates or stores that provider login.

Do not follow a command sequence from this page. Open Setup in the app (workspace nav → Setup). It renders every command you need, resolved for the deployment you are actually looking at, with nothing to fill in — and it reports what the server has observed after each one, so you never have to guess whether a step worked. Setup is the single source; what follows is the reference for why each step exists and what it costs you.

Install. One command installs @jentrix/cli and @jentrix/runner together, registers the Claude Code plugin, signs you in through the browser, and offers to make the folder session-ready. Both packages are required: without the runner, jentrix session refuses with RUNNER_NOT_INSTALLED. Setup also carries the two local checks (jentrix --version, jentrix whoami) for the one fact the server cannot see — whether this machine has the toolchain.

Sign in. Sessions are attributed to you, not to a service token. The installer runs jentrix login, which opens the browser for OAuth (authorization code + PKCE) and stores a rotating token in the CLI config, mode 0600, never printed. Never export a copy of it: it dies at the next rotation, mid-session, as a confusing 401. On the consent screen you choose the scopes and, optionally, pin the credential to one workspace:

Leave it unpinned if you work across workspaces — session start then discovers matching projects everywhere your account reaches.
If you pin it, cross-workspace project discovery is disabled by design (the consent screen warns you at the moment of choosing). An interactive session start still gets the normal confirmation picker — scoped to the pinned workspace, behind an explicit banner saying other workspaces were not searched — while non-interactive runs must pass --project <id> (PROJECT_DISCOVERY_REQUIRES_UNPINNED_LOGIN).

Connect the repository. A session never picks a workspace directly — it binds to a project, and the project locks the workspace. jentrix align (Setup's step 02) establishes that binding interactively. The repo→project mapping is a durable link that satisfies the session repo gate any of three ways:

Project repo link — add the repository as owner/name under project settings → Linked items (or over MCP with add_project_link). You don't have to leave the terminal for this one: when a session start hits PROJECT_REPO_MISMATCH, the CLI offers to add the link right there (needs workspace ADMIN + admin scope) and retries. New here? Set up your first project explains the shape.
GitHub-linked board — on a full deployment, a repo already connected through GitHub sync to a board the project uses counts too.
Workspace default repository — when no project in the workspace carries an explicit repo link, sessions fall back to the workspace default: the defaultRepo set via update_workspace, or — when unset — the workspace's sole GitHub-linked repository, inferred automatically. Project settings shows the default a session would inherit and where it came from.

To check every precondition at once — the credential and its pin, the runner install, spool-root writability, the repository identity, project resolution, and the repo link — run the doctor from inside the checkout:

jentrix session doctor

Session start itself inspects the checkout (normalized owner/name, branch, HEAD — never an absolute path server-side), resolves matching projects, and always asks you to confirm before anything is created. No match prints PROJECT_REQUIRED with the exact fix; several matches present a pick list (non-interactive runs must pass --project).

4. Run it

Claude Code

jentrix session claude              # or: --project <id-or-slug>

Confirm the project and the Jentrix session is created before Claude Code launches; the runner then starts Claude Code interactively with capture hooks injected for just that session. Work exactly as you normally would. When you exit, capture is verified, usage receipts are aggregated, and the RUN_SUMMARY is stored.

Codex

jentrix session codex               # same flow on the Codex SDK runtime

While it runs, and afterwards

jentrix session status              # your active sessions + capture health
jentrix session end <session-id>    # close out explicitly (also verifies capture)
jentrix session claude --resume <jentrix-session-id>   # continue an INTERRUPTED session

jentrix session status <id> also reports local capture liveness — whether the capture host process is alive and when the spool last grew — because the server cannot see the local capture leg. A session that is bound server-side but recording nothing on this machine is visible immediately, not after the abandonment window: when THIS machine's credential bound the session and no capture footprint exists at all, the capture line reads bound server-side; local capture NOT RUNNING instead of "recording", and the CLI says the same thing loudly if the capture host exits while the server still shows the session open.

jentrix session end <id> defers to a live local capture host when one is running: the host flushes the spool, submits the verified manifest, and completes the session itself; the CLI reports the host's verdict. Only when no live host exists does end complete server-side directly.

In Jentrix, the project's Runs tab lists the session with honest usage ("Not reported" when a runtime doesn't expose receipts — never a fabricated 0), and Artifacts holds the redacted transcript parts and the summary.

Click the session id on the Runs tab to open the session transcript viewer: the stored TRACE parts stitched into one readable conversation — messages, collapsible tool calls and results, per-turn usage receipts, and a kind filter — with a Download full transcript (.ndjson) link for the raw stream as a single file. The viewer only reads what capture stored: an expired, redacted, or never-acknowledged part is declared as a visible gap (and as a leading # comment line in the download), never silently skipped, and a line the parser cannot read renders as visible damage rather than disappearing.

Attaching a session you already started

If Claude Code is already running without Jentrix, install the Jentrix plugin (jentrix plugin install) and run /jentrix-connect inside the session — the session id comes from trusted lifecycle hooks, never from model-authored text. The universal fallback from another terminal:

jentrix session attach --provider claude [--project <id>] [--watch]
jentrix session attach --provider codex --provider-session <thread-id>

When the trusted transcript path is available (the plugin's hook context, or --transcript-path), a Claude attach starts the capture host — in the foreground with --watch, otherwise detached in the background (the attach output names the host pid; jentrix session status <id> shows its liveness and jentrix session end <id> hands it the finalize request). When no transcript path exists — including every codex attach, which records the thread binding only — the CLI says SESSION BOUND BUT NOT RECORDING at the moment of attach instead of claiming capture began.

History from before the attach point is honestly out of coverage unless you pass --import-history where the provider supports it; the summary names the gap either way.

If something goes wrong

First move: jentrix session doctor — it re-checks every precondition and reports all failures at once. Specific symptoms:

Symptom	Meaning / fix
`RUNNER_NOT_INSTALLED`	`npm install -g @jentrix/runner`, retry.
`PROJECT_REQUIRED: no project links repository …`	Add the repo link (project settings → Linked items, or `add_project_link`), retry.
`PROJECT_REPO_MISMATCH`	The confirmed project doesn't link the checkout repo. Interactive sessions offer to add the link on the spot and retry; otherwise add it as above.
`PROJECT_DISCOVERY_REQUIRES_UNPINNED_LOGIN`	Non-interactive with a workspace-pinned login — pass `--project <id>`. An interactive terminal gets the pin-scoped picker automatically.
`capture pending` / non-zero exit at end	Network loss: the local spool (mode `0600`, already redacted) is retained and re-uploaded; the command exits 0 only when every part is acknowledged.
`SESSION BOUND BUT NOT RECORDING`	Printed at attach when no capture host could start (no transcript path; every codex attach), or later when the host died after the bind — either way the server can't see it and would show the session healthy until the sweep. `jentrix session end <id>` closes it honestly now (the gap is recorded), or resume once it turns `INTERRUPTED`.
Session shows `INTERRUPTED`	The 5-minute liveness window lapsed (crash, sleep). `jentrix session claude --resume <id>` from the same repository continues it.

Capture health is also surfaced operationally: sessions with incomplete capture appear in the Control Tower's session-capture queue.