Overview

Current status

jackin❯ is a functional proof of concept, not a stable product line. Claude Code, Codex, Amp, Kimi, OpenCode, and Grok ship today as built-in agent runtimes, with namespaced roles, workspace management, per-mount isolation for parallel agents, layered authentication forwarding (including 1Password references), and an interactive operator console (TUI). The roadmap below is expected to change aggressively as the project learns which concepts deserve to survive.

Completed

• Brand identity system — terminal-native rebrand: the jackin❯ wordmark on the phosphor green-block mark (black word, white chevron, square corners only), the old apostrophe wordmark retired across docs, README, Rust, and config, regenerated favicons / app icons / Open Graph / README hero, the construct-image j❯ prompt sigil, and the frozen-rain jackin --help banner plus jackin --version splash. Canonical spec at /reference/brand-identity/. Deferred: desktop/mobile apps, hosted analytics, auto host-prompt install, a brand-kit download page.
• Architecture Decision Records — ten foundational ADRs written and published at /reference/adrs/, covering workspace structure, Rust tooling, TUI rendering, capsule rendering, editor state, container backend lifecycle, launch/reconnect boundaries, role-hook ownership, and cleanup approval.
• Ratatui terminal modernization — jackin-term and the Capsule emit path now share one explicit terminal contract: a profile-owned display-width table, completed SGR/underline/hyperlink fidelity, an attach-capability state matrix, and removal of the full-frame repaint sentinel for true Ratatui buffer-diff output. Real-terminal soak passed after fixing two soak-found bugs (a resize-collapse capsule panic and a resize border-residue over the status bar). Scroll-region/DECSTBM output is deliberately deferred — semantic ScrollOp records only — and Termina migration and inline images remain out of scope. See the Capsule Terminal Model reference for the shipped contract.
• Claude Code and Codex agent runtimes with full-speed mode (--dangerously-skip-permissions / YOLO) inside the container boundary
• Layered authentication forwarding per (workspace × role × agent) — sync / api_key / oauth_token / ignore for Claude Code, and sync / api_key / ignore for Codex, Amp, Kimi, and OpenCode (none supports oauth_token)
• Docker container isolation with Docker-in-Docker
• Interactive operator console (TUI) with workspace, role, and agent selection
• Workspace management (create, edit, remove, prune, list, show, plus env and claude-token subcommands) — CLI and TUI
• Global mount configuration with role scoping
• Role repository contract validation
• Derived Dockerfile generation with UID/GID remapping
• State persistence across sessions
• Agent identity (display names)
• UID/GID host user mapping at runtime — docker run --user $HOST_UID:$HOST_GID --group-add 0 plus libnss-extrausers passwd/group entries and group-0 image home permissions make host-owned bind-mounts transparently writable without baking the UID/GID into the image; see Construct Image: User Creation Responsibility for the design and the documented usermod + gosu alternative
• GitHub CLI authentication state persists across container restarts (forwarding host login on launch is tracked separately under GitHub CLI authentication strategy)
• Homebrew distribution via jackin-project/homebrew-tap
• Namespaced roles (e.g., chainargos/frontend-engineer)
• Last-agent memory per workspace
• Custom Claude Code plugin marketplaces in jackin.role.toml — see the role manifest reference
• Sensitive mount path warnings (warn-and-confirm for ~/.ssh, ~/.aws, etc.) — see the Mounts guide and the Security model
• Automatic orphaned DinD cleanup (pre-launch garbage collection)
• ${env.VAR} interpolation in env var prompts and defaults for dependent variables
• JACKIN_DIND_HOSTNAME environment variable for agents to discover the DinD sidecar hostname — see the Environment variables guide
• Agent source trust model (trust-on-first-use verification for third-party role repos)
• DinD TLS authentication with auto-generated certificates — see the Security model and Architecture
• JACKIN_DEBUG environment variable — verbose tracing for shell commands and jackin internals; documented inline in every command page
• MSRV toolchain pin — rust-toolchain.toml enforced in CI
• Worktree cleanup on container removal — orphaned host-side worktrees no longer accumulate
• jackin eject — stop and clean per-container state (with --all and --purge)
• jackin prune family — orphaned roles, derived images, cache, and instance state
• jackin config trust grant | revoke | list — explicit CLI management of role-source trust beyond the trust-on-first-use prompts
• Per-workspace git_pull_on_entry — opt-in host repo refresh at launch via --git-pull / --no-git-pull
• macOS keep-awake reconciler — --keep-awake / --no-keep-awake workspace flags hold the system awake while an agent is active
• Per-mount isolation for parallel agents — shared | worktree | clone modes implemented in V1
• Split config.toml into per-workspace files — ~/.config/jackin/workspaces/<name>.toml layout shipped with per-file version stamps and migration
• Global mount visibility and editing — workspace views show applicable global mounts separately, and the console has a dedicated global mounts editor for ~/.config/jackin/config.toml. See the Mounts guide
• Settings TUI — the console has a tabbed Settings shell covering existing jackin config surfaces: global mounts, global/per-role env vars, global auth forwarding modes, and role source trust
• Project structure map refresh — PROJECT_STRUCTURE.md now covers the root file/workflow map and delegates detailed source navigation to the Codebase Map
• Unique container identity and restore — DNS-safe unique container identities, per-instance manifests and rebuildable index, hardline/load/console recovery flows, durable per-instance agent home restore, related-instance recovery/rebuild, moved ad-hoc path recovery, guarded purge, hardline --new, and Java Testcontainers DinD smoke coverage have shipped; operator workflow is documented in Parallel Agents, contributor details live in Runtime Instance Model, and reconnectable named sessions plus persistent lifecycle history are tracked separately
• Role authoring CLI — desktop role creation, validation, and migration are documented in the role command reference and Creating a Role; the standalone CI/Renovate-style validator split is documented in Architecture and Schema Versions
• Async Docker API via bollard — DockerApi trait, BollardDockerClient, FakeDockerClient, ContainerState (all 9 Docker lifecycle states); typed API for lifecycle, cleanup, inspect, exec, and image operations, replacing CLI stderr string-matching; docker build, docker exec -it, and docker run -it stay on the CLI by design — see Codebase Map for details
• Z.AI (GLM Coding Plan) as an alternative provider for Claude Code and OpenCode sessions — ZAI_API_KEY env injection, model mapping (ANTHROPIC_DEFAULT_*_MODEL), in-container and console provider picker, and AuthKind::Zai auth tab row; see Z.AI authentication
• Shared TUI scroll model — scrollbar geometry, clamping, cursor-follow offsets, drag/click mapping, launch-progress tail scrolling, and capsule scrollback all route through jackin_tui::scroll while keeping console and capsule visuals distinct; see TUI Design Decisions
• Docs site migration to Fumadocs on TanStack Start — the docs build now runs through Vite/Bun, statically prerenders GitHub Pages output under .output/public, ships static Orama search, AI-readable llms.txt and per-page Markdown, Takumi-generated OG/social/icon images, custom /sitemap.xml, and the React landing/docs chrome. Contributor details live in Codebase Map.
• TUI architecture — Ratatui application patterns — all three TUI surfaces (jackin-console, jackin-launch-tui, jackin-capsule) follow one Elm Architecture layout with typed effects, pure views, and shared components in jackin-tui. See TUI Design Decisions for the binding design rules and Codebase Map for the module layout.
• Codebase readability & restructuring foundation — tiered Cargo workspace, dependency DAG with no upward edges, zero mod.rs files in extracted crates, command-dispatch and operator-env split work resolved, and clippy -D warnings green across all targets. The remaining root jackin integration layer and console extraction ledger are documented in Codebase map.
• Phase 2 file-split foundation — the largest production modules flagged for review-size pressure have been decomposed into focused sibling modules under coordinator files, and the file-size/test-layout exception ledgers are empty. The PR #664 merge-readiness blockers are closed: restored prewarm CLI constraints, launch-failure modal behavior, required CI wiring for the strict gates, and shrink-only ratchet behavior. The Codebase health: structure & reviewability item remains Partially implemented for the remaining root/launch/TUI/editor follow-ups.
• Post-restructure correctness & polish fixes — completed the branch-wide cleanup after the workspace split: shared TUI primitives, the owned jackin-term terminal model, the provider-catalog port onto the workspace crate structure, the AgentRuntime / Provider registry work, per-scope auth-sync source folders, structured diagnostics/metrics, zero-dead-code hygiene, and latest-stable Rust CI policy. Durable docs now live in Capsule Terminal Model, Architecture, Agent Authentication, Run Diagnostics, TUI Design Decisions, and Codebase Map.
• Agent runtime status authority — implemented, shipped across Phases 0–12: PTY/keystrokes no longer author state (the byte-driven flap engine is deleted; sessions start Unknown); the daemon tick is the sole state path (arbitrate → watchdog → debounce → publish); the semantic reporter channel, /proc physics, OSC evidence, and the screen rule-pack engine (recursive nested-gate grammar, engine-version floor, semver-bounded validated versions) all feed arbitration; seen/ack, flap/stuck telemetry, status explain/capture, per-launch reporter installation, and derived-image asset copying have landed. Two CI guardrails keep it honest: an unlinked-source hard error and a status-truthfulness check that fails if this page claims "Implemented" while the tree is unwired; the page is the design record + per-phase checklist.
• Capsule usage overlay — read-only per-provider account quota interface for jackin-capsule (overview plus per-provider tabs, status-bar headline mapping, cache-backed refresh, honest stale/refreshing/unavailable states, real reset epochs, and the focused-agent tab model built on the shared TabStrip component) is fully shipped; see Capsule reference.
• Claude Fable and limits-array usage windows — the Capsule usage overlay parses Anthropic's limits array, surfaces per-model weekly windows such as Fable on both OAuth and CLI fallback paths, backfills partial responses from legacy named windows, and names model-scoped bottlenecks in compact status rows; see Capsule reference.
• Parallel Agent Coordination — per-tab JACKIN_AGENT_CODENAME identity, read-only jackin-capsule agents registry (human + --format json), tab-hover codename tooltip, and host jackin status per-agent codename table all shipped.

Partially implemented

• jackin-exec: Secure Execution Wrapper — the full mechanism is wired and shipped end to end: control protocol, capsule dispatch, host.sock resolver, on-demand filtering, JACKIN_EXEC_BINDINGS injection, MCP server registration, current EnvValue::Extended/OpRef.on_demand schema, and the ExecPicker dialog; Linux host.sock caller authentication now uses peer credentials, while non-Linux/Docker Desktop coverage remains with the daemon track; remaining work is one credential-materialization gap and a live smoke pass through jackin load
• Docker runtime hardening contract — Docker profile enforcement is wired end to end: egress allowlist injection with fail-closed firewall apply, the locked Docker-internal network, the launch session contract with per-decision telemetry, the standard-profile compatibility matrix, the standard compiled default, and the rootless DinD tier; rootless DinD is a recommended explicit grant, and the roadmap tracks credential env-only posture
• 1Password integration — env references and picker flows are documented in standard docs; roadmap tracks future read-only secret file mounts
• Multi-runtime support for Codex, Amp, Kimi, OpenCode, and Grok — built-in runtime launch for all six agent runtimes is documented in standard docs; roadmap tracks deeper runtime parity
• GitHub CLI authentication strategy — shipped GitHub auth forwarding is documented in standard docs; roadmap tracks the CLI subcommand, scope pre-flight, and deeper GHE coverage
• Auth reliability and convenience program — Phase 0 (new-tab overwrite fix) and Phase 1 (multi-company source folders) are shipped, and Phase 2 and Phase 5 have shipped baseline pieces with real gaps remaining; Phases 3, 4, 6, and 7 are still open design proposals
• Auth overwrite on new tab — root-cause fix shipped for the bug where opening a new agent tab overwrites in-container credentials with the stale launch-time snapshot; live cross-session sync remains deferred to the daemon program
• Workspace Claude token setup — CLI setup/rotate/revoke/doctor, 1Password write and validation, the expiry banner, host-side PTY OAuth-token onboarding, the shared op_picker Create mode, the plain-prompt --interactive storage-location picker, and the console Auth-tab generate-token action are all shipped; roadmap tracks the canonical oauth_token auth slot, an Apple Keychain backend, a pre-launch validity probe, and bulk migration
• Config versioning and migration framework — shipped per-file schema gates for config, workspace files, and role manifests, plus automatic config/workspace migration, desktop role manifest migration through jackin role migrate, and CI migration through jackin-role migrate; roadmap tracks deferred --pr automation and the Renovate-style auto-migration GitHub Action
• Console agent session control — instance discovery, console workspace tree-view with expandable instance rows and session pane, hardline --shell, in-container multiplexer primary session, secondary agent sessions via hardline --new, agent runtime status authority integration, and console a/x/N/X/T/P instance keybindings (with the P purge gated behind a confirmation modal) shipped; Phase 4 still tracks live session reconciliation and resource panel integration
• jackin❯ Capsule control plane — Phases 1–3 are shipped in full: jackin-capsule is the PID 1 in-container PTY multiplexer built on jackin-term DamageGrid, tmux is fully removed from the derived image and the host CLI, and every terminal-fidelity item once tracked as remaining (resize, mouse, focus events, OSC/CSI passthrough, prefix-key input, git-context-driven title/branch bar) is live, alongside the agent runtime status authority integration. Phase 4 (host daemon integration and the Desktop Agent Hub bridge) remains open, alongside a smaller set of real control-channel and passthrough gaps
• Launch progress TUI — run IDs, JSONL diagnostics, instance-lifecycle boundary rain gating, structured launch stages, compact/rich/test renderers, console-triggered launch reuse, and reduced-motion support shipped; roadmap tracks diagnostics viewer, broader rich-render snapshots, and deeper startup parallelization
• Alternative LLM providers (MiniMax, Kimi, GLM everywhere) — provider catalog, Claude Code routing, MiniMax Codex routing, OpenCode routing, Auth-tab key support for Z.AI/MiniMax/Kimi, the N-provider launch picker, provider tab labels, per-provider role-manifest model overrides, and operator guides for Z.AI/MiniMax/Kimi have shipped; Codex GLM/Z.AI and Codex Kimi remain deferred until those providers expose a Responses-compatible endpoint, and remaining work is provider-catalog polish (config-generation drift, availability/update detection, keeping provider docs aligned with upstream changes)
• Operator CLI hygiene — Phases 1–4 shipped: jackin doctor with pre-flight checks, jackin status/ps fleet overview, --format json for workspace list/show and status/doctor, jackin load --dry-run plan preview, JackinError E001–E016 friendly error layer; Phase 5 (first-run wizard) deferred pending UX design
• Security threat model & signed releases — security implementation doc, CI signing (cosign + SLSA + SBOM) for all release/preview workflows, operator verification guide, cargo xtask release-verify archive verification proven against jackin-dev-v0.1.13, and sigstore-rs in-process capsule manifest verification with embedded Rekor key shipped; the clean-cache capsule download path still needs its first end-to-end run against a real signed bundle
• Runtime Restore and Image Architecture — image bake, home seeding, container identity, the restore ladder, schema migration, console instance surfaces, launch cockpit hard-exit, build-performance work, and the in-capsule dirty-exit flow (shared detection, the exit modal, host keep/discard execution) have all landed in code; remaining work is operator live end-to-end signoff and the Inspect diff pane
• Network egress policy — Docker grant-based allowlists, launch-contract enforcement-quality reporting, and the fail-closed Capsule guest firewall exist for the role container; roadmap tracks DinD-inner-container coverage, rule editing, connection decision logs, service-port policy, and non-Docker backend parity
• Session keep and resume — dirty/unsafe exit assessment with a rich exit dialog (return/keep/discard) and an optional file-level Inspect surface, durable per-instance host state, the "Unfinished jackin instances" restore picker, launch-recipe identity pins (role SHA, base image ref/digest, image tag), stopped-container docker start reconnect paths, and purge/prune machinery (terminal-status pruning, orphan-lock reaping, stale-active reconciliation) are shipped; roadmap tracks a "keep to resume" outcome for clean sessions, extending the per-workspace exit policy to clean exits, recreate/rebuild tiers with full launch-recipe replay, socket-dir/sidecar rematerialization for the stopped-container restore path, launch-time index reconciliation, and continuity-framed resume UX
• Workspace-native PR verification — jackin-dev pr sync/path/env/status/explain/clean exists for local PR bundles; roadmap tracks console-native review mode, per-project recipes, docs preview automation, companion role pinning, and generic verification command execution
• Test infrastructure & behavioral specs — insta snapshot testing and cargo-fuzz (for jackin-term, scheduled nightly) are in use; roadmap tracks a shared jackin-test-support crate, mega-test-file splits, behavioral specs for the capsule daemon and operator console, and proptest/fuzz coverage for parser surfaces
• Declarative resource limits — operator-level [docker.grants] (memory, memory_reservation, cpus, pids, nofile) are shipped, validated, and translated to Docker flags, and OOM kills are detected, preserved, and surfaced in jackin status; roadmap tracks one-shot per-field CLI overrides, non-Docker backend translation, and a push-notified OOM signal
• Operator handler system — host affordance primitives (safe URL open, verified file export, host reveal/open) are shipped and documented; roadmap tracks the configurable named-handler layer ([handler] config, jackin open/diff/web, console keybindings)
• Credential source pattern — EnvValue covers literals, host-env references, structured op:// refs, and on-demand jackin-exec delivery, reused by auth and provider-key console pickers; roadmap tracks a general CredentialSource abstraction spanning non-env consumers (command, OS secret store, file backends)
• Auth health and operator visibility — Capsule exposes usage/account status surfaces for running sessions, launch records auth provisioning outcomes, jackin doctor checks coarse GitHub CLI auth, and jackin config auth show prints global modes; roadmap tracks per-agent credential health probes, jackin auth status, config-wide probes, and console Auth-tab health glyphs
• Apple Container backend — macOS ARM backend using Apple's native container CLI for VM-per-workload isolation: launch-path backend selection, manifest schema, and session-contract/telemetry output are wired and compile; roadmap tracks command-path lifecycle dispatch (reconnect/eject/purge) and Phase 0 hardware validation
• Workspace registry cache — outer image freshness, prewarm, and capsule image-cache behavior exist; roadmap tracks the future DinD inner-registry / zot workspace cache
• Host affordance bridge — an opt-in host-owned attach client behind JACKIN_HOST_ATTACH=1 ships clipboard image paste (with chunked large-image transfer), explicit image-path staging, GitHub PR/CI open actions, visible-URL open with modifier-hover disclosure, minimal chunked container file export, and diagnostics/launch-failure reveal-or-open, documented in the Host Affordances guide; the remaining gate before promoting the opt-in path to default is live end-to-end validation in Ghostty/OrbStack, not more implementation surface
• jackin❯ Context Engine — design spec, evidence base, rollout plan, and reuse matrix are documented in the research corpus; roadmap tracks implementation of crates/jackin-context across the P0–P6 phases, starting with measurement and ending with routing and memory
• Codebase readability leaves — jackin❯-native spec-driven workflow, op-picker behavioral spec, runtime launch behavioral spec, PROJECT_STRUCTURE.md freshness gate, Developer Reference setup, module contracts, per-directory README + AGENTS.md, and pub(crate) visibility are the setup/readability leaves behind the codebase-health program. Several are resolved setup records; the remaining ones are specific maintenance gates or split prerequisites, not broad research dossiers.
• Remaining split leaves — Split input/editor.rs, Split runtime/launch.rs, and Unify settings/editor surfaces are the still-actionable file/surface simplification tasks.
• Agent orchestration task leaves — Session contract and explain mode, Stack integration contracts, Session snapshot and rollback, Ephemeral mount modes, Workspace description field, Agent tag protocol, Console resource panel, Custom operator tools, GitHub link tracking, Idle runtime cleanup hooks, Autonomous task queue, Task source abstraction, jackin-remote, and Workspace skills mount are still-open design proposals under the agent-orchestration program. Research context lives under /reference/research/; these pages track what remains to build or decide.

Planned

Platform expansion

• Kubernetes platform support — run agents on Kubernetes clusters instead of local Docker, enabling team-scale deployments and production debug containers. The vision is to use jackin❯ as a debug container in production environments — safely exploring issues with AI agent assistance inside a controlled Kubernetes pod.

Security improvements

• Credential proxy — proxy-based credential injection to avoid storing tokens inside containers
• Agent version pinning — pin role repos to tagged versions for reproducible builds, with explicit --update to advance (status: open — design proposal)

Reactive daemon program

• jackin❯ daemon — umbrella — introduce the long-running per-operator-user host process jackin❯ will use for reactive features. Plans 047/048 shipped lifecycle/socket commands plus the first muted-by-default attention snapshot adapter; live auth sync, host bridge, Desktop Agent Hub APIs, and keep-awake migration remain deferred to follow-up plans
• Live bidirectional auth sync — Phase 2 adapter. Keep host and every running container in lock-step on each auth axis (gh, Claude, Codex, Amp, …). Subsumes the launch-time sync mode's bidirectional follow-up; deferred until the daemon foundation proves secret redaction, coredump handling, version-skew failure, and lifecycle restart behavior (status: deferred)
• Agent attention prompts — Phase 2 adapter. Host-side OS notifications when an agent inside a Capsule-managed role container is waiting on operator input or has finished unseen work. The feature-gated Plan 042 prototype consumes the agent runtime status authority and emits blocked / done edge notifications; production OS notifications and click-to-focus remain follow-up work (status: spiked)
• Host bridge — secrets and approved host actions — Phase 3 adapter. Operator-mediated channel for agents to request a single secret value or invoke a single host command without tearing down the container. Deferred until the daemon foundation and per-request approval/audit contract are proven because this adapter exposes the highest-risk host action surface (status: deferred)

Infrastructure improvements

• Registry configurations — a configurations layer for private registries: multiple named, globally-or-per-workspace-scoped endpoint configurations, each sourcing credentials through the credential-source pattern (env, command, op://, Docker credential store/helper, ECR helper), so jackin can pull private images (Amazon ECR, private GHCR/Docker Hub) instead of silently failing auth and rebuilding from the Dockerfile (status: open — design proposal)
• Platform support policy & roadmap freshness — declare macOS as primary platform, Linux as experimental, Windows WSL2 as best-effort, native Windows as out of scope; document Debian-only construct image rationale; add last_reviewed frontmatter and freshness check script for every roadmap item (status: open — design proposal)

Operator surface and fleet operations

• jackin join & debug export — research jackin join <org>/<project> for project-level onboarding with TUI wizard (auto-clone, credential config, workspace setup) and a diagnostic export command that produces a redacted .tar.zst debug bundle for bug reports and AI agent analysis (status: open — research and design proposal)
• Source branch policy for isolated mounts — make worktree and clone mounts choose their base from host HEAD, the host's current branch, the repository default branch, a named branch, or an ask-on-launch dialog, with a redesigned console isolation-settings dialog replacing the current one-key cycle (status: open — design proposal)
• Agent launch flags API — baseline launch-flag behavior is shipped; the data-driven override API (static API in jackin.role.toml, runtime API via the construct-image binary, and Rust dispatch replacing bash case statements) is unimplemented. Default dangerous-mode behavior preserved; role authors will be able to override or extend (status: open — baseline shipped, override API unimplemented)

Codebase health

• Open review findings catalog — living backlog of review findings with accepted-exception annotations; five confirmed findings currently need fixes (two previously-cataloged rows were verified resolved and dropped). Code review and automated scanning consult this catalog (see AGENTS.md → "Code review & automated scanning") (status: open)

Documentation infrastructure

• Markdown linting for docs — uniform Markdown lint pipeline for the docs site (status: open — adoption plan drafted, no implementation committed)
• Rustdoc → Fumadocs integration — surface rustdoc JSON inside the Fumadocs docs site (status: deferred — Phase 3)

Vision

The user-facing summary of where jackin❯ is headed lives on the Why jackin❯? → Vision page so it is visible to operators and role authors, not only to contributors who end up on the roadmap. The longer-term shape of the project, the local-first focus, and the eventual move toward Kubernetes-backed debug workflows are all captured there.

If jackin❯ works for your use case — or almost works but needs something different — open an issue or submit a pull request.

Contributing

jackin❯ is open source under the Apache 2.0 license. To develop and test jackin❯ itself, use The Architect — a dedicated agent with the full Rust toolchain:

jackin load the-architect

The project uses cargo-nextest for testing and requires all clippy lints to pass before committing.