Kernel CLI

Connect Kernel to Codex or T3 Code on your host (see T3 Code). Choose Link to Codex → New task on a Kernel task, then choose Draft or Work and a destination. Work also lets you set model and reasoning. Conversations and approvals stay in Codex; Kernel shows execution status and a direct link.

Install and connect

Requires macOS or Linux, Node 22–24, pnpm, and a signed-in Codex installation. Linux also requires tmux.

pnpm add -g @supercorks/krnl
krnl login
krnl connect codex

If pnpm reports ERR_PNPM_NO_GLOBAL_BIN_DIR, run pnpm setup, open a new Terminal tab, and retry the install.

krnl login opens Kernel in your default browser. Sign in with your invited Kernel account and choose Connect CLI. Return to Terminal when the browser says the login is finishing.

krnl connect codex asks once for access to all current and future compatible saved Codex projects for that Kernel account. It registers this Mac, installs status hooks, and starts a background companion that runs at login. It prints the exact Codex command and /hooks instructions if the new hooks need review. Review the eight Kernel hooks and restart open Codex tasks afterward. The companion detects completed review automatically.

Open Settings → Integrations → Codex in Kernel to map an organization or project to a saved Codex project. Your Mac and saved projects appear automatically. Each connection card contains its organization and project mappings. Choose Add mapping or Edit to set the destination, model, reasoning, and an optional task name prefix. New mappings default to GPT-6 Astra · xhigh; choices come from that Mac’s current Codex model catalog. Launches stay disabled until setup is ready; one unavailable project does not disable healthy projects. Delete connection revokes its authorization and removes its mappings, while keeping existing tasks, handoff history, receipts, and worktrees.

No repository checkout, build tools, copied IDs, or per-folder authorization commands are needed. Installing the npm package alone does not start a service or change Codex configuration.

Linux and remote hosts (0.3.0+)

Install and connect the companion on the host where the projects and agent run. Each host gets its own Kernel connection; existing Mac mappings remain available. Use Work to start remote threads or Existing task/thread to link them. Desktop drafts remain available on Macs.

For browser sign-in over SSH, forward an unused loopback port from your computer:

ssh -L 43821:127.0.0.1:43821 your-ssh-host

Then run on the remote host:

pnpm add -g @supercorks/krnl@latest
krnl login --no-browser --callback-port 43821
krnl connect codex
krnl connect t3code
krnl status

Open the printed Kernel sign-in link on your computer while the SSH forward is connected. The callback listens only on the remote loopback interface. Cancel with Ctrl+C. For an alternate Codex profile, set CODEX_HOME when connecting; the background service retains that profile. Save the remote folders as Codex projects in the same profile and complete its Kernel hook review. For T3 Code, use a pairing link from that remote environment, not the Mac's local environment.

Linux stores state and owner-only credential files beneath ~/.local/share/kernel/ (directories 0700, credentials 0600). It starts each companion in an isolated kernel-companion tmux server, so closing SSH leaves it running. A failed companion restarts after 30 seconds. After restarting the host or its container, run krnl connect codex / krnl connect t3code again. It does not install a system-wide service or change your host's startup policy. krnl disconnect stops only the selected connection. On macOS, existing Keychain storage and launchd startup are unchanged.

Keep Codex Desktop/Remote Control connected to the same remote profile to continue its threads. T3 Code's desktop or mobile client must be paired to the remote environment for its thread links.

Commands

| Command | Purpose | | ----------------------- | ---------------------------------------------------------------------------- | | krnl login | Sign in through Kernel in the browser. | | krnl connect codex | Connect, resume interrupted setup, or repair/update this Mac’s installation. | | krnl status | Check the account, connection, saved project count, and remaining setup. | | krnl disconnect codex | Revoke this connection and remove its login service; keep your CLI login. | | krnl logout | Disconnect and remove the local CLI login. |

For another Kernel deployment, use krnl login --origin https://your-kernel.example. HTTP is accepted only for loopback development. Log out before switching deployments.

To update:

pnpm add -g @supercorks/krnl@latest
krnl connect codex

Version 0.1.1 or later is required to launch with mapping model and reasoning settings. Version 0.1.2 or later also supports linking an existing Codex task. Version 0.1.5 or later adds durable delivery recovery, cancellation support, and task-status freshness when the Kernel server supports it. Version 0.1.6 or later recognizes interrupted turns with a saved completion timestamp as Done with “Stopped in Codex.”, including after reconnecting. An interrupted status without that timestamp remains uncertain because it can also describe a turn still running in desktop. Version 0.1.7 or later keeps the Kernel card's title synchronized with renames in Codex, including completed tasks, when the server supports it. This does not rename the Kernel task. Status and explanatory text share one row, for example Done · Stopped in Codex. Version 0.1.3 or later supports mapping task name prefixes. For example, a prefix of 👩‍⚕️ creates 👩‍⚕️ MELLA-284: Investigate an issue. A blank prefix keeps the normal name. Project mapping settings take precedence over organization settings, and changes apply only to new tasks. Kernel and this companion use the current protocol together.

Repeated connection reuses the machine identity. Review changed hook commands in /hooks if Node moved. After updating Node, run krnl connect codex to refresh the service’s executable path.

Projects and compatibility

The companion uses saved project identities from Codex’s app-server. Initial support covers projects with one accessible local folder. Git mappings default to a new worktree from refs/remotes/origin/HEAD; choose Existing folder under the mapping’s Advanced settings if needed. Non-Git projects use their saved folder. Missing folders, multi-root projects, and disabled project hooks are explained beside that project in Kernel.

New Work checkouts live in Codex's configured worktree directory (normally ~/.codex/worktrees/<full-task-id>/<repository-name>), so Desktop can group them under the selected saved project. Each task still has its own branch and checkout. Existing checkouts and their saved paths are preserved when the companion updates.

CLI 0.1.14 repairs first-turn metadata added by 0.1.13 to historical linked tasks or drafts. It retries the resulting codex_not_work delivery rejection while preserving the task, checkout, receipt, and delivery history. These tasks remain observation-only.

Tested Codex capabilities: desktop 26.908.40834 with bundled CLI 0.154.0-alpha.6.2. The companion prefers /Applications/ChatGPT.app/Contents/Resources/codex, falling back to codex on PATH. The app-server capabilities are experimental, so other Codex versions require verification.

In Kernel, Stop beside Open in Codex interrupts the companion-owned first Work turn and releases the same saved task to desktop. Kernel shows Stopping… until release is confirmed, then Stopped. Continue in Codex. It stays open and does not send a new message, mark the Kernel task complete, or discard completed work. If confirmation takes longer than fifteen seconds, Retry Stop retains the same durable request. Desktop continuations, Drafts, and linked tasks have no Stop control in Kernel.

The companion releases its first-turn app-server after completion or a request for input. Continue in desktop after that release; an interrupted structured question may be asked again. Kernel observes Running/Done across later desktop turns through hooks. It does not answer questions or approve commands.

Existing companion installations keep their allowlist until you explicitly upgrade through krnl login and krnl connect codex. The upgrade retains their machine identity, mappings, and handoff history when the existing connection is still authorized.

Link an existing task

On a Kernel task, choose Link to Codex, then the Existing task tab. Search by the current Codex task title (at least three characters) or paste a codex://threads/<task-id> link, select the match, and choose Link task. Choose a Mac if more than one is connected. Only tasks in compatible, locally authorized saved projects appear. Archived tasks are labeled.

Linking adds monitoring and a direct Codex link; it never starts a turn, changes its model, or changes its folder. A Codex task can be associated with one Kernel task per Mac; linking it again to that same task returns the existing association.

Search uses a short-lived local metadata cache and never searches messages or previews. Kernel receives at most 25 matching titles and destination metadata per lookup. Searches expire after 30 seconds, with resolved matches available for two minutes. Refine a broad query or paste a deep link if the catalog cannot be searched in time.

Completed tasks become Done after their saved turn metadata is checked. A task already executing or awaiting input when linked can remain Disconnected until its next status hook; continue in Codex normally. Subsequent hooks provide Running, waiting, and Done transitions.

Local data and troubleshooting

The executable is copied to a stable location under ~/Library/Application Support/Kernel/Codex/bin/. Hook and service paths do not depend on global package folders or temporary installer caches. launchd services live under ~/Library/LaunchAgents. Closing Terminal does not stop the service.

CLI credentials use macOS Keychain service Kernel CLI; machine credentials use Kernel Codex companion. Codex credentials stay local. Browser URLs never contain these credentials. The browser returns a short-lived authorization code to a temporary 127.0.0.1 callback, protected with state and PKCE. CLI sessions last 90 days; run krnl login again after expiry.

Run krnl status first when disconnected, then krnl connect codex to repair setup. If Kernel revoked the Mac remotely, sign in again with krnl login before reconnecting. If revocation cannot reach Kernel, the disconnect command stops the local service and asks you to retry online.

Disconnect and logout preserve Codex tasks, local creation receipts, and worktrees. Hooks retain only lifecycle metadata for tasks launched or explicitly linked through this connection. Neither transcripts nor attachment contents are uploaded. Keep receipts intact when investigating an uncertain launch; the companion will reconcile creation before retrying an acknowledgement and will not repeat an uncertain turn.

Homebrew, a native setup app, and a one-command npx setup flow are not included in this release.

Draft and Work (0.1.4+)

Draft opens Codex with the saved task prepared in its composer. Choose Plan in Codex if you want, then send. Keep the Kernel link in the prompt: its reference lets the local status hook associate the new thread automatically. Kernel shows the pending draft until submission, then a direct thread link and Running/Done status. If you remove the reference, link the thread through Kernel's Existing task tab using its deep link or a title search.

Draft uses the saved project folder and desktop model/reasoning settings. Work applies the mapping's settings and starts the first turn through app-server; the task is visible in desktop but cannot accept desktop replies until that turn finishes or is released for input. Choose Plan inside Codex after opening a Draft; Kernel dispatches only Draft and Work.

Both modes use the same concise instructions: gather context from the task before starting, and ask the user when something is unclear. Task details appear in a fenced YAML block, with null or empty fields omitted and meaningful false and 0 values preserved. Draft keeps its task title first and its automatic-linking reference in the YAML href field. The prompt also asks for approval for any proposed Kernel task updates when the work is done.

CLI 0.1.12 requires the prompt rendered and frozen by Kernel at submission. It forwards that text unchanged and has no local prompt template. Future wording and YAML changes need only a web deployment. Work also requires resolved model/reasoning settings; neither is supplied by a legacy fallback. Heartbeats and status reports use the current format without feature negotiation.

Deploy Kernel and update this companion together. Setup uses krnl login and krnl connect codex with all-saved-project consent; manual pairing and per-project allowlist commands are removed. For this one-time cutover, convert settled old launch receipts to current watch records while the service is stopped and its local lock is held. Preserve a private backup and all task IDs, status sequences and delivery state. Do not interrupt an active first turn to perform the cutover.

Interrupted draft dispatch is not repeated automatically. If Kernel cannot confirm opening, check Codex before opening another draft. Hooks inspect only the submitted prompt to match a pending reference; they do not retain or upload the edited prompt or read transcripts.

Network recovery (0.1.5+)

Heartbeats, project discovery, local observations, task launches, and delivery run independently. Temporary network failures and server throttling retry automatically with bounded backoff and Retry-After support. Local receipt acknowledgments and retry progress survive a restart. A lost creation or turn acknowledgment is reconciled without executing the task again. Expired launch offers are never executed after reconnecting.

krnl status also shows the last successful delivery, pending and blocked counts, oldest pending age, and recovery instructions. Permanently rejected items and damaged journals remain on disk for diagnosis. This command reads local diagnostics and works without network access. Healthy tasks continue independently. Do not delete receipts or blocked records to retry an uncertain launch. Remote revocation stops dispatch; run krnl login and krnl connect codex to authorize again. A connection replaced by another process requires krnl connect codex.

Kernel expires machine connectivity after 30 seconds. It also expires each task observation after at most 90 seconds; a heartbeat alone does not make an old task status current. Uncertain or expired observations show Disconnected until trustworthy evidence returns. Supported Codex metadata cannot reconstruct every missed desktop event, especially a turn already running or waiting for input. Open the task in Codex when its state cannot be verified.

Kernel's launch form offers Cancel during extended waits. Cancellation is effective before the companion claims the launch; afterward, continue in Codex. Search has a separate Cancel action, a 30-second total deadline, and never applies late results after cancellation. Browser timeouts preserve input and cached content so the same request can be reconciled safely.

Shared threads (0.1.8+)

One Codex thread can be linked to several Kernel tasks through each task's Existing task tab. Every linked task receives activity and waiting status; linking or completing a Codex turn does not change the Kernel tasks' lifecycle. Linking the same thread to the same task again is safe. Install the current CLI and run krnl connect codex with the current Kernel server. Hooks update every association and retain an event until all receipt writes succeed, including across restarts.

CLI 0.1.13 adds first-turn ownership reports and durable stop delivery. Deploy the matching Kernel migration and web contract before updating this package. Startup enriches historical receipts with unknown ownership; it never assumes that a Desktop turn belongs to the companion. An accepted stop survives network failures. After restart, release is confirmed only when the saved owner's exit or process-identity replacement can be proved; inaccessible process metadata remains unknown. Wait for active first turns to finish before restarting the service to upgrade.

T3 Code (0.2.0+)

krnl connect t3code pairs Kernel with the T3 Code app on this Mac. It is independent of Codex; one login can hold both connections. Keep T3 Code open while connecting.

krnl login
krnl connect t3code

The companion finds the running T3 Code server from $T3CODE_HOME, then ~/.t3-fork (T3 Code fork), then ~/.t3. It asks once for permission to start and follow threads in your T3 Code projects, then asks for a pairing link: in T3 Code open Settings → Connections, choose Create pairing link, then Copy link. The companion exchanges the link for a session limited to orchestration:read orchestration:operate; it cannot open terminals or change T3 Code access. The session is kept in the Keychain (Kernel T3 Code session). The T3 Cork fork does not expire sessions narrowed to these scopes; the official app's last 30 days. krnl status shows the expiry; run krnl connect t3code again to renew an expiring one.

What the companion does, all through T3 Code's public HTTP API and one-shot WebSocket calls:

• Catalog: T3 Code's projects (with the local Git default branch) and configured provider instances, models and model options. Instance names are reported as-is.
• Work: one thread.turn.start that creates the thread (its ID is the Kernel launch ID), prepares a new worktree and runs the project setup script when the mapping asks for one, then starts the first turn with the chosen instance, model, options, permission mode and interaction mode. After a restart the companion checks for the thread before doing anything; it never repeats creation.
• Draft: opens t3cork://app/new?projectId=…&prompt=…, which puts the task into a new T3 Code composer without sending it. When you send it, the companion matches the Kernel reference in the first message to the draft and links the thread. The message is read in memory only.
• Status: Running, waiting for an approval or an answer, or Done, from each linked thread's shell. Nothing from the conversation is sent to Kernel except the thread title.
• Stop: interrupts whatever Kernel shows as Running, including background work that outlived its turn, and confirms once T3 Code reports nothing live.
• Existing thread: title search over T3 Code's threads, or a pasted t3cork://app/<environment>/<thread> link.

Kernel shows the connection as disconnected while T3 Code is closed; launches are not queued. krnl disconnect t3code stops the service and revokes the Kernel connection. Revoke the companion's session in T3 Code under Settings → Connections if you no longer need it. Local state lives in ~/Library/Application Support/Kernel/T3Code/machines/<id>/.