Use Auktra with Codex.

01 / OVERVIEW

A local workspace for the projects you choose.

Auktra collects policy-filtered receipts from supported Codex hooks in Git projects you explicitly connect. It turns those retained records into sessions you can revisit, source details you can inspect, and findings you write for your next review. It does not scan your home folder or import earlier Codex history.

This guide covers the invited private beta tested on Apple silicon macOS with Node 26.7.0 and Codex CLI 0.160.0. Use a fresh Auktra installation and a disposable, non-sensitive project. Choose Metadata only during setup. Other architectures or versions need a separate compatibility check from the founder.

Optional account for the auth candidate

Use website sign-in to view an approved release. After you install that exact candidate, auktra start asks for recording consent separately. Signing in never enables recording and does not upload local evidence.

auktra start
auktra login
auktra whoami

Login uses Google through Clerk and returns to a temporary loopback callback on 127.0.0.1. An explicit login may reuse a still-valid bound refresh grant without reopening the browser. To switch accounts, log out first and then sign in again:

auktra logout
auktra login

02 / INSTALLATION

Verify the private package before installing.

Your invite supplies auktra.tgz privately. A .tgz file is a compressed npm install package; you do not need an Auktra source checkout. In Terminal, move to the folder that contains the supplied file and run every preflight check below.

uname -m
node --version
codex --version
git --version
command -v auktra
npm ls -g --depth=0 @auktra/local
shasum -a 256 auktra.tgz

Continue only when the architecture is arm64, Node reports v26.7.0, Codex reports codex-cli 0.160.0, Git is available, and the archive matches the exact current beta checksum:

70f52719b77234b662cb8623222ab45178a62894b73ea34e7e8ca436268471ed

Verify that value against your trusted invite. An empty global npm listing may exit 1; that is expected when Auktra is absent. If command -v auktra or the npm list shows an existing installation, or if any version or hash differs, stop and contact the founder. Do not overwrite an existing installation.

npm install -g ./auktra.tgz
auktra help

Use your normal user-owned npm setup. Stop on an install error; do not add sudo or --force. If the file is elsewhere, keep its quoted absolute path on one line:

npm install -g "/Users/you/Downloads/auktra.tgz"

Replace /Users/you/Downloads/auktra.tgz with the package’s actual absolute path on your Mac before running the copied command.

03 / FIRST SESSION

Record one known, harmless request.

Close Codex before setup. Create a disposable Git project, start Auktra, and choose option 1 · Metadata only. Auktra prints the canonical Git root you must use for Codex.

mkdir auktra-beta-check
cd auktra-beta-check
git init
auktra start

Then check the generated project hooks and their installed runtime paths.

auktra doctor

Doctor should report Project hooks: EXACT_OWNED_GROUPS_PRESENT and Runtime paths: MATCH. Those results confirm configuration only; they do not prove that a fresh receipt has arrived.

Review the generated hooks in Codex

From the exact project root Auktra printed, start Codex. Inside Codex, open Follow Codex’s normal project-trust prompt for this disposable project. Then open /hooks and review and trust all seven generated definitions. Codex trusts the exact definition hash, so new or changed hooks require a fresh review. This follows the official Codex hook review guidance.

codex

/hooks

After trust is complete, give Codex one known request:

Create hello.txt containing hello Auktra, then run cat hello.txt.

In a second Terminal window, return to the same project root and open the workspace. Keep that terminal running. If the browser does not open, use the private localhost URL printed there.

auktra open

Find the fresh session and open View source. Confirm that its received timestamp belongs to this test instead of relying on an older total count.

04 / DAILY USE

Install once. Opt in one project at a time.

Run auktra start once for each Git project you choose. Recording stays configured until you run auktra stop; you do not need to start it before every later session unless you stopped it or changed its settings. For later sessions, launch Codex from the connected project root and review any hooks Codex marks as changed.

You may call auktra start [directory] while you are elsewhere inside a Git project or pass a project directory explicitly. Codex itself must still launch from the canonical root printed by Auktra. For another project, run start there and complete the hook review again.

Closing the browser or pressing Control-C in the dashboard terminal stops that local dashboard server. It does not stop capture in connected projects. Use auktra stop in each project when you want recording disabled.

05 / DASHBOARD

Move from a session list to its source record.

The main navigation includes All sessions, Projects, Recently viewed, and Saved findings. Session labels describe retained evidence, such as Recent activity, Status unknown, or a received lifecycle signal. They do not claim that Codex is currently running.

A finding is human-authored, not an automatic diagnosis. Its note remains until you delete it. The linked source can expire, be purged, or become unavailable after a project is disconnected, while your note remains with an unavailable source link. The current beta does not add a separate export or sharing workflow.

06 / EVIDENCE AND LIMITS

Understand what each receipt tells you.

A receipt is a policy-filtered record of a supported hook Auktra received. It is not the complete hook payload, a full transcript, or Codex internal reasoning. The beta supports UserPromptSubmit, PreToolUse, and PostToolUse, plus lifecycle signals SessionStart, Stop, Interrupt, and SessionEnd. Here, Stop means a response ended; it is unrelated to auktra stop and does not establish session completion.

Supported tool projections include selected fields from tools such as shell and apply-patch calls. Do not assume every field from every MCP tool is captured. In source records, OMITTED · CONTENT_NOT_ENABLED means content capture was off, UNAVAILABLE · FIELD_NOT_RECORDED means the field was not retained, and REDACTED means a privacy rule removed text before storage. Content omitted in an earlier session cannot be recovered by enabling another mode later.

The following is a schematic example, not a live receipt or a promise of every field. The fictional receivedAt value is integer milliseconds since the Unix epoch.

{
  "id": "<receipt-id>",
  "digest": "<permitted-content-sha256>",
  "receivedAt": 1791158400000,
  "evidence": {
    "profile": "<capture-profile>",
    "policy": "<policy-version>",
    "kind": "PostToolUse",
    "sessionId": "<session-id>",
    "toolName": "shell",
    "command": { "availability": "OMITTED", "reason": "CONTENT_NOT_ENABLED" },
    "reportedExitCode": 0
  }
}

Source view exposes available receipt ID, digest, received time, profile, policy, session ID, and supported tool metadata. Receipt order is not proven execution order or cause. A reported exit 0 is the hook’s reported field, not independent proof that the task succeeded. Recent activity is a recent receipt, not a live-process signal. Counts and gaps describe retained groups, not complete session coverage.

Status separates settings from evidence: ENABLED or DISABLED reports recording consent; RECEIPTS_OBSERVED means retained receipts exist, which can include old records. Doctor’s runtime-path match checks configuration. To confirm new delivery, make a fresh known request and inspect its fresh source timestamp.

07 / COMMAND REFERENCE

The commands you’ll use.

In the table, [directory] means an optional actual project path. Do not type the square brackets literally.

Automation and advanced local options

For a noninteractive metadata-only setup, --yes is part of the full start command below. Selected-content mode exists behind separate consent, but its privacy filtering is incomplete and it is not recommended for this beta quickstart. Do not use a --yes --content quickstart here.

auktra start --yes

A private absolute state folder is optional. Use the same --state value for start and open. For open or demo, --no-open keeps the browser closed and --port 0 selects an available port. State is not accepted by demo, stop, status, or doctor. Replace /Users/you/.auktra-private with the actual absolute private folder you want to use on your Mac before running either line.

auktra start --state "/Users/you/.auktra-private"

Choose Metadata only and wait for setup to finish. Then open a second Terminal in the same project and use the same state path:

auktra open --state "/Users/you/.auktra-private" --no-open --port 0

08 / PRIVACY AND RETENTION

Your workspace and evidence stay local.

The default workspace state is under ~/.auktra-workspace. Each configured project keeps its evidence under .auktra/recorder. The current beta does not upload trace evidence to an Auktra cloud service. Codex provider traffic is separate from Auktra. Metadata, project paths, notes, receipt timing, and tool names can still be sensitive, so use only an approved non-sensitive test project.

Evidence has a seven-day retention window. Recorder commands apply expiry; there is no claim that an idle process removes a record at the exact instant it ages out. Saving a finding does not extend the linked evidence period. Copies you put in reports or backups are separate and remain until you remove those copies. Changing to metadata-only mode or stopping capture affects future receipts; it does not remove older retained selected-content receipts that are still within retention.

The optional auth candidate may display a private local cache of the signed-in account ID, email address, and display name for up to 30 days. Passive status reads do not write that cache or run idle erasure. A refresh grant is kept in macOS Keychain; its provider lifetime and revocation are separate. auktra logout clears local account state, while account credentials are never returned by the Auktra account API. Switching or removing an account does not remove the same operating-system user’s local evidence; delete evidence through the documented workspace controls when that is your intent.

09 / TROUBLESHOOTING

Find help for common problems.

auktra: command not found

Check your user-owned npm global binary directory in PATH, then open a new Terminal. Do not retry with sudo.

ENOENT for the archive

Return to the folder containing auktra.tgz, or use one quoted absolute path on one command line.

GIT_PROJECT_REQUIRED

Change into the intended repository root, initialize the disposable folder with git init, or pass the Git project directory to the project command.

No new session or events

Confirm the correct project, run auktra status and auktra doctor, review all hooks in Codex, confirm Codex 0.160.0, and make a fresh known request in the approved test project. Enabled consent and matching configuration alone do not prove healthy delivery.

Search looks empty

Global search covers retained prompt, command, and result text. Metadata-only mode records those values as omitted, so there is no hidden text to search.

Localhost page is unavailable

Keep the auktra open terminal running or reopen the workspace. Use the exact printed localhost URL and do not share a private tokenized URL.

A field or source is unavailable

Check its availability reason and retention age. Expired, omitted, redacted, or never-recorded content is not automatically a runtime failure.

An install already exists

Stop. Do not overwrite or force an upgrade. Contact the founder for the version-specific path.

When asking for help, send sanitized version output and status symptoms only. Do not send evidence contents, credentials, project source, saved notes, or private localhost URLs.

10 / STOP AND REMOVE

Disable every project before removing the runtime.

End Codex first. In every opted-in project, stop recording and inspect the result. Require recording to report DISABLED before continuing.

auktra stop
auktra status

Then remove Auktra’s exact owned hooks from that project:

AUKTRA_RUNTIME="$(npm root -g)/@auktra/local/recorder/auktra-evidence.mjs"
node "$AUKTRA_RUNTIME" uninstall --project "$PWD" --confirm-hook-removal

Only after every project is stopped and its owned hooks are removed should you uninstall the global package. Do not delete the runtime first; configured hooks would still point to it.

npm uninstall -g @auktra/local

Retained evidence and saved findings remain after uninstall. Stop and contact the founder if revocation, hook removal, or uninstall fails. The current beta has no automatic overwrite or upgrade path.