Codectx

An always-present contextual HUD for humans, virtual agents, and coding tools.

Codectx projects the minimum operational information a worker needs to perceive its current environment, focus, constraints, risks, and available moves without stopping work to reconstruct context through a separate interface.

The current repository implements Codectx's first proven lens: deterministic repository context. It observes a Git repository, combines explicit focus with project commands and imported external signals, and emits one bounded projection for human HUD, machine consumption, review, and handoff.

Git remains repository authority. Codectx is a projection and attention system, not a task database, proof authority, workflow orchestrator, or source of domain truth.

The canonical HUD direction and migration boundaries are defined in docs/codectx-hud-v0/README.md.

Product direction

World, runtime, repository, Orb, and domain sources
                         ↓
                  Codectx lenses
                         ↓
               composed projection
                         ↓
       ambient HUD / machine view / review / handoff

Codectx should eventually remain continuously available through a host runtime or device such as Orb. The worker should normally acquire context by perception rather than by opening another application and navigating to the relevant state.

The current CLI remains valid. It is the first explicit shell and proof surface for the projection model, not obsolete scaffolding awaiting ceremonial deletion.

Implemented repository lens

• human-readable HUD through plain codectx;
• deterministic machine packet through codectx --json;
• Git root, branch, HEAD, dirty files, and baseline-relative changes;
• explicit focus from .codectx/focus.toml or --focus PATH;
• expected, supporting, unexpected, and unclassified path handling;
• public justfile command discovery with definition hashes;
• codectx review reviewer output;
• codectx handoff durable JSON handoff;
• Runseal records imported as external claims with unknown freshness;
• the earlier session runtime preserved as codectx-legacy.

Codectx does not currently implement an ambient compositor runtime, continuous subscriptions, lens registration, Orb integration, closure resolution, state-bound evidence execution, generic risk assessment, orchestration, repository indexing, a daemon, or a database.

Quickstart

git clone https://github.com/greygoody/codectx.git
cd codectx
cargo build -p codectx-cli --bins
mkdir -p .codectx
cp .codectx/focus.example.toml .codectx/focus.toml
./target/debug/codectx

Primary surfaces:

./target/debug/codectx
./target/debug/codectx --json
./target/debug/codectx review
./target/debug/codectx handoff

The default handoff path is .codectx/handoffs/latest.json. The repository ignores .codectx/focus.toml and .codectx/handoffs/, so normal local use does not manufacture new repository noise.

Focus declaration

id = "CX-0001"
title = "Add deterministic context packet output"
summary = "Expose focused repository state to implementers and reviewers."

expected_paths = [
  "crates/codectx-core/**",
  "crates/codectx-cli/**",
]

supporting_paths = [
  "README.md",
  "docs/**",
  ".github/**",
]

constraints = [
  "preserve Git as repository authority",
  "do not promote external claims into proof",
  "derive human and JSON output from one packet",
]

The default .codectx/focus.toml is optional. When it is absent, Codectx reports focus_missing and leaves changed paths unclassified.

An explicitly requested path is a different contract. This fails instead of silently degrading to no focus:

codectx --focus missing-focus.toml

Fixture-backed product walkthrough

Run the committed demonstration:

bash scripts/demo.sh

The script copies fixtures/context-demo/repository into a temporary Git repository, commits its baseline, and applies one expected source change, one supporting documentation change, and one unexpected operations change.

It verifies the HUD, review, deterministic JSON, public command discovery, hidden-command filtering, external-claim boundary, attention items, and byte equality between codectx --json and the default handoff.

Human HUD example

CODECTX · context

Location
  demo · <fixture-head>

Focus
  DEMO-0001 · Add request tracing
  Keep request-tracing changes focused while preserving the repository command surface.

Changes
  expected 1 · supporting 1 · unexpected 1 · unclassified 0

Attention
  - external_obligation_open: Runseal closure RS-DEMO externally reports status open.
  - unexpected_changes: 1 changed path(s) do not match the declared focus.

Next
  Inspect unexpected changes
  Changed paths fall outside the declared expected and supporting paths.
  run: git diff --stat

Review example

Changed paths
  - README.md [Supporting]
  - ops/emergency.toml [Unexpected]
  - src/lib.rs [Expected]

Constraints
  - keep the public API stable
  - keep Git provenance visible
  - treat imported obligation status as an external claim

Available commands
  - just check
  - just format

JSON excerpt

{
  "schema_version": 1,
  "repository": {
    "root": "<fixture-repository>",
    "branch": "demo",
    "head": "<fixture-head>"
  },
  "focus": {
    "id": "DEMO-0001",
    "title": "Add request tracing"
  },
  "changes": {
    "changed_files": [
      { "path": "README.md", "relevance": "supporting" },
      { "path": "ops/emergency.toml", "relevance": "unexpected" },
      { "path": "src/lib.rs", "relevance": "expected" }
    ]
  },
  "runnables": [
    { "id": "check", "command": "just check", "visibility": "public" },
    { "id": "format", "command": "just format", "visibility": "public" }
  ],
  "external_signals": [
    {
      "id": "RS-DEMO",
      "epistemic_status": "external_claim",
      "freshness": "unknown"
    }
  ]
}

Projection authority

Runseal owns persistent obligations, typed conditions, evidence semantics, resolution, and regression.

./target/debug/codectx \
  --runseal-closure ../runseal/closures/RS-0001.toml

Imported records remain external claims with unknown freshness. Codectx observes the record; it does not independently validate the obligation or promote its status into Codectx-owned truth.

Git / focus / justfile / external record
                   ↓
             ContextPacket v1
                   ↓
        HUD / JSON / review / handoff

In the broader direction, ContextPacket v1 becomes the compatibility contract for the repository lens. It is not silently redefined into a universal HUD schema.

Context state classes

Future Codectx projections should preserve three origins:

derived
  computed from observed sources

managed
  supplied or required by a runtime, device, authority, or policy source

explicit
  changed by a deliberate user or bearer move

Current focus files and CLI options are explicit input. Git observations and change relevance are derived. Imported external records remain managed external claims only when their source and authority are preserved.

v0.2 interface decisions

Legacy commands

The previous bounded-session runtime is explicitly available as:

./target/debug/codectx-legacy --help

For v0.2 compatibility, implemented historical commands such as codectx enter, codectx ok, and codectx prove are forwarded to the sibling codectx-legacy binary when both binaries are installed together. codectx check is an explicit alias mapped to legacy ok. Commands not implemented by the preserved legacy binary, including events, are not advertised. This is an intentional compatibility policy, not shared semantics between the two runtimes.

Legacy manually recorded proof remains an attestation, not repository-state-bound evidence.

Handoff output

The primary managed destination is .codectx/handoffs/latest.json, and the walkthrough proves that path. v0.2 also retains codectx handoff --output PATH for explicit integrations. Arbitrary output is not used by the normal repository workflow.

Architecture

crates/codectx-core
  repository observation, command discovery, packet construction, renderers

crates/codectx-cli
  explicit HUD shell, machine packet, review, handoff, compatibility binary

crates/codectx-protocol
  historical session/event protocol used by compatibility code

Target direction, not implemented in Step 1:

Codectx lenses
  bounded context providers

Codectx compositor
  attention, priority, visibility, and projection composition

Codectx surfaces
  ambient HUD, CLI, machine API, review, and handoff renderers

Host runtime or device
  subscriptions, lifecycle, delivery, persistence, and authority integration

See docs/context-packet-v1.md, docs/implementation-status.md, and docs/codectx-hud-v0/README.md.

Proof

just check

Equivalent witnesses:

cargo fmt --all --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace
cargo run -p codectx-cli --bin codectx -- --help
bash scripts/demo.sh

Design rules

1. Context is a projection, not domain authority.
2. Codectx reduces context acquisition from an interaction into perception.
3. Observed, derived, managed, explicit, external claim, and unknown remain distinguishable.
4. Git stays visible and authoritative for repository state.
5. Missing data is not fabricated.
6. Human and machine views derive from bounded deterministic projections.
7. Attention is prioritized; healthy state should collapse rather than occupy the entire field of view.
8. Codectx suggests or exposes moves but does not award completion or manufacture authorization.
9. External systems retain ownership of their semantics.
10. Writes remain within explicit Codectx artifact or move boundaries.
11. The current repository lens and ContextPacket v1 remain compatibility surfaces until versioned successors are proven.