Codebase Map

This page is a contributor’s map of the jackin’ source tree. It is written for people who want to understand how jackin’ is built, debug its internals, or work on the project itself. If you only want to use jackin’, start at Concepts and the Operator Guide — you do not need this page.

Note

This page is the canonical module map for jackin’. When module structure changes, this page is updated in the same PR — see the “Code ↔ Docs Cross-Reference” table in PROJECT_STRUCTURE.md. PROJECT_STRUCTURE.md itself is a short, agent-facing pointer that covers the multi-repo ecosystem and the per-PR docs contract; it sends readers here for the actual module-level detail.

Repository layout

Path	What lives there
src/	Rust CLI binary — every command jackin’ implements
docker/construct/	Source for the shared base Docker image (projectjackin/construct:trixie)
docker/runtime/entrypoint.sh	The entrypoint script jackin’ injects into every derived image at /jackin/runtime/entrypoint.sh
docs/	This documentation site (Astro + Starlight)
.github/workflows/	CI for jackin’, the construct image, and the docs site
tests/	End-to-end and integration tests

Where to start reading

Different contribution shapes have different natural entry points.

”I want to add or change a CLI flag”

Start at src/cli/mod.rs — the top-level Cli and Command enum. Each subcommand has its own clap module:

Subcommand	Module
load / hardline / console	src/cli/role.rs
role	src/cli/role.rs and src/role_authoring.rs
eject / purge	src/cli/cleanup.rs
prune	src/cli/prune.rs
workspace	src/cli/workspace.rs
config	src/cli/config.rs
exile (unit variant)	src/cli/mod.rs
Bare jackin / console dispatch	src/cli/dispatch.rs

Command dispatch lives in src/app/. Every clap subcommand has a match arm in src/app/mod.rs (run) that calls into the relevant domain module (workspace/, runtime/, config/, etc.). When you add a flag, also update the matching docs page under docs/src/content/docs/commands/.

”I want to change container lifecycle behaviour”

The container lifecycle lives in src/runtime/:

• src/runtime/launch.rs — the load path: clone/update role repo, validate the contract, generate a derived Dockerfile, build the image on the host Docker engine, start the DinD sidecar and the agent container, attach.
• src/runtime/attach.rs — the attach + reconnect path (hardline).
• src/runtime/cleanup.rs — eject, exile, purge, prune (roles/cache/images/instances), and orphan GC.
• src/runtime/image.rs — docker build invocation.
• src/runtime/repo_cache.rs — the role-repo cache lock
  • fetch logic.
• src/runtime/caffeinate.rs — the macOS keep-awake reconciler.

Instance-local state helpers live in src/instance/:

• src/instance/mod.rs — role state preparation and auth materialization re-exports.
• src/instance/auth.rs — Claude, Codex, Amp, OpenCode, and GitHub auth file provisioning.
• src/instance/naming.rs — DNS-safe container name generation (jk-{id}-{workspace?}-{role}), instance-ID extraction, and role-family matching. Image tag derivation (jk_…) lives in src/runtime/naming.rs.
• src/instance/manifest.rs — per-instance instance.json identity records, lifecycle status, and the rebuildable instances.json lookup index.

The end-to-end shape of “what happens when you run jackin load” is described in Architecture → Container lifecycle. The detailed contract for instance names, manifests, lookup indexes, restore decisions, cleanup guards, and parallel sessions lives in Runtime Instance Model.

”I want to change workspace or mount behaviour”

The workspace model is in src/workspace/:

• src/workspace/mod.rs — types and re-exports.
• src/workspace/mounts.rs — mount parsing and validation.
• src/workspace/planner.rs — plan_create, plan_edit, plan_collapse (the redundant-mount invariant).
• src/workspace/resolve.rs — runtime resolution from workspace + ad-hoc + global mounts.
• src/workspace/sensitive.rs — sensitive-mount detection for the warn-and-confirm gate.

Per-mount isolation (worktree / clone) lives in a separate module because it has its own materialization lifecycle:

• src/isolation/materialize.rs — worktree and clone materialization + MaterializedWorkspace.
• src/isolation/state.rs — isolation.json IO.
• src/isolation/finalize.rs — the post-attach finalizer that decides between preserve / clean / return-to-agent.

”I want to change a config-file shape”

The TOML config model lives in src/config/:

• src/config/mod.rs — top-level AppConfig struct and submodule re-exports.
• src/config/persist.rs — AppConfig::load_or_init (config-load + builtin sync).
• src/config/editor.rs — ConfigEditor (the save path used by every CLI mutator).
• src/config/workspaces.rs — workspace CRUD plus the require_workspace helper.
• src/config/mounts.rs, src/config/roles.rs — CRUD and resolution per area (global mounts; builtin sync, trust, and auth-forward).

Whenever a config field changes, also update Configuration File so the schema reference stays accurate.

”I want to change role-manifest behaviour”

The jackin.role.toml schema, validator, migration chain, and role-authoring entrypoints live across a small set of files:

• src/manifest/mod.rs — schema structs, load, display_name.
• src/manifest/validate.rs — RoleManifest::validate and validate_agent_consistency.
• src/manifest/migrations.rs — manifest version registry and file migration.
• src/repo.rs — role-repo contract validation shared by local commands and runtime repo resolution.
• src/role_authoring.rs — desktop role-authoring commands for creating, validating, and migrating local role repositories.
• src/bin/validate.rs — standalone role-focused validation and migration binary used by GitHub Actions and future Renovate-style automation.

Whenever the manifest schema changes, also update Role Manifest.

”I want to change the operator console (TUI)”

The interactive console lives in src/console/:

• src/console/mod.rs — run_console entrypoint, event loop, and the quit-confirm overlay; per-screen drawing lives under src/console/manager/render/.
• src/console/state.rs — ConsoleState and WorkspaceChoice.
• src/console/preview.rs — workspace preview and detail lines.
• src/console/manager/ — the workspace-manager TUI subsystem.
• src/console/widgets/ — reusable modal and widget components.

General terminal-UI helpers (palette, intro/outro animation, prompt helpers) are split out into src/tui/.

Cross-cutting helpers

A handful of files at the crate root own concerns that don’t cluster into a single module:

File	Owns
src/env_model.rs	Reserved-runtime-env list, is_reserved, interpolation reference extraction, topological env order with cycle detection.
src/env_resolver.rs	Runtime env resolution — interpolation, interactive prompts.
src/selector.rs	Role-selector parsing (agent-smith, chainargos/backend-engineer, …).
src/repo.rs	Role-repo validation — required files, path-traversal checks.
src/repo_contract.rs	Enforces that role Dockerfiles extend the construct base.
src/derived_image.rs	Generates the derived Dockerfile from the role’s repo + the construct base.
src/docker.rs	Docker command builder — CommandRunner trait and ShellRunner.
src/paths.rs	XDG-compliant data and config directory resolution (JackinPaths).

Code ↔ docs cross-reference

When a code change affects user-visible behaviour, the matching docs page must change in the same PR. The full table lives at the bottom of PROJECT_STRUCTURE.md; the most common pairings are:

Code change in	Update docs in
src/cli/**	Commands
src/workspace/** (mount logic)	Workspaces, Mounts
src/config/**	Configuration File
src/runtime/**	Architecture, Runtime Instance Model
src/instance/**	Runtime Instance Model
src/isolation/**	Workspaces (per-mount isolation), Architecture (materialization + finalizer), Configuration File
src/manifest/**	Role Manifest
src/instance/auth.rs	Authentication, Security Model
src/derived_image.rs	Construct Image
docker/construct/Dockerfile	Construct Image

Docs site source

The docs site (this site) is an Astro + Starlight project under docs/. Bun is the only supported package manager.

Path	Purpose
docs/astro.config.ts	Site metadata, sidebar layout, edit-link target
docs/src/content/docs/	All MDX content — file path maps to URL
docs/src/components/overrides/	Starlight component overrides (Head, SiteTitle, …)
docs/src/pages/index.astro	Landing route — plain Astro page, NOT a Starlight content entry

To run the site locally:

cd docs
bun install --frozen-lockfile
bun run dev   # http://localhost:4321/

Contributor entry points

If you have not contributed before, these files are worth reading first:

• AGENTS.md — house rules (apply equally to humans and agents).
• CONTRIBUTING.md — contribution flow, DCO sign-off.
• BRANCHING.md — branch naming and merge policy.
• COMMITS.md — Conventional Commits format.
• TESTING.md — how to run the test suite.
• PROJECT_STRUCTURE.md — agent-facing pointer covering the multi-repo ecosystem and the per-PR docs contract; the detailed module map this page surfaces is the source of truth.

The Roadmap is the catalogue of in-flight and planned design work. When picking up a task, the matching roadmap entry usually has the problem statement, the chosen approach, and the related source files.