Control Artuditu from Codex

The optional Artuditu Codex skill provides agent delegation and full session control. It covers workspaces, tabs, panes, agents, files, Git, DIFF notes, worktrees, tasks, leases, modules, themes, Artuditu Bar, UI state, optional resume integrations, and Universal Harness Protocol 1.0.

Inside a Artuditu pane, the skill uses that pane’s inherited binary, socket, and pane identity. This lets the same skill delegate and control the current Artuditu session without guessing which server owns the pane.

Outside Artuditu, the skill resolves the installed artu command and controls its configured production session. With the default configuration this is the server at ~/.artuditu/artuditu.sock.

For a named server, include the selector in the request or command:

artu --session api agent list
artu --session api pane focus 7

The skill preserves the inherited socket inside a managed pane. Outside a pane, an explicit --session wins over any inherited socket. It does not run session list, help, or ping before an ordinary operation, so named-session routing adds no discovery round trip to the fast command path.

Enable the Artuditu skill

The Codex marketplace plugin already includes the Artuditu skill. When using Artuditu without that plugin, opt in to the version-matched skill bundled with the Artuditu binary:

artu skill enable

The command makes no network request. It detects supported coding-agent environments and installs the one bundled Artuditu skill through their native skill directories. The shared ~/.agents/skills/artuditu/ destination serves Codex, GitHub Copilot CLI, Gemini CLI, Pi, Cursor, Amp, Droid, and fx. Claude Code, OpenCode, Kimi Code CLI, Grok Build, Qwen Code, and Kiro use their native dedicated destinations. It does not add an always-on pointer to ~/.codex/AGENTS.md, and it never overwrites an installation it does not own.

Start a new Codex thread after enabling the skill. Confirm its release, path, and integrity at any time with:

artu skill status

The status command reports Artuditu-managed filesystem installations. A Codex marketplace plugin lives in Codex’s private plugin cache, so it is intentionally not reported there even though its bundled Artuditu skill is available to Codex.

Connect to Artuditu

The skill supports two modes:

• Managed pane: Codex is running inside Artuditu. The skill uses the injected ARTUDITU_BIN_PATH, ARTUDITU_SOCKET_PATH, and ARTUDITU_PANE_ID values exactly. It controls only that inherited session and never substitutes another socket or binary.
• External terminal: Codex is running in any other local terminal. The skill resolves the installed artu command from PATH and uses its configured production session.

Approve local socket access in the Codex app

The Codex app normally runs shell commands in a workspace sandbox. Artuditu uses a local Unix socket outside that workspace, so the app will ask for permission before ping or another control command. Approve the request if you want that thread to operate Artuditu.

Without this approval, the operating system returns the same connection error as an offline server. The skill retries with explicit permission and reports Artuditu access was not approved when permission is declined. It only reports the server offline after an approved connection attempt fails.

Do not disable the Codex sandbox globally. The skill requests only the local execution permission when it needs to connect to Artuditu.

Install and start Artuditu

The skill works with every supported Artuditu installation method:

curl -fsSL https://artu.jdev.run/install.sh | sudo sh

Only one installation method is needed. Confirm the command is available, then start the production server when it is not already running:

artu --version
artu server start

The skill supports custom production locations. If ARTUDITU_HOME or ARTUDITU_SOCKET_PATH is explicitly configured, it preserves that configuration. Otherwise the installed release uses ~/.artuditu/artuditu.sock. The skill never runs bare artu for discovery because that launches or attaches the interactive TUI.

Ask Codex to control the session

Use $artuditu when you want to invoke the skill explicitly:

Use $artuditu to show the active workspaces, tabs, panes, and agents.

Inside Artuditu, start a line with =target to delegate the rest of that line:

=reviewer inspect the current diff
=7 run the test suite
=codex fix the parser

The target can be a live agent name, pane id, or unique agent kind. The marker must be the first non-whitespace character on the line. $ remains reserved for Codex skill invocation.

Try requests such as:

Show me every coding agent running in Artuditu.

Split a pane on the right, run the tests there, and show me the result.

Inspect the active workspace, Git state, tasks, and path leases.

Read the visible screen of the blocked Codex agent before answering it.

Use UHP for harness automation

The skill keeps ordinary control on the faster semantic CLI path. It uses UHP only when you explicitly ask for a Artuditu API, harness integration, live schema, sequenced events, revision-safe automation, delegated access, or terminal streaming.

For UHP work it begins with the selected running server’s contract:

artu uhp capabilities
artu uhp schema
artu uhp snapshot

The skill follows the returned method contracts and limits instead of assuming that the website and installed release match. It handles fenced snapshots, event replay and resynchronization, mutation revisions, scoped expiring tokens, and exclusive terminal-control streams. Routine delegation still uses agent prompt, agent read, and other semantic commands rather than raw terminal control.

CLI widget commands are named artu bar; the corresponding UHP method family is ui.bar.*. Agent detection remains a core Artuditu feature. Optional integration install hooks are used only when you explicitly request native session resume or lifecycle reporting, never as a prerequisite for sidebar detection.

Fork an agent session

The skill can fork a supported live agent into a sibling pane while the original keeps running. Resolve the source first, then optionally name the new fork or preserve the current focus:

artu agent get reviewer
artu agent fork reviewer --name experiment --no-focus

The fork inherits the source conversation and receives its own new session. Native forks currently support Claude, Grok, Codex, and Pi. If the target is unsupported, its session cannot be resolved, or its pane cannot start, the skill reports Artuditu’s structured error instead of substituting a split, new agent, or resume operation that could lose or reuse the wrong context.

Arrange panes and tabs

The skill can move a running pane to another tab without restarting its process, or append a new tab for it. Resolve the pane and inspect the tabs in its workspace before changing the layout:

artu pane move 7 --tab 2
artu pane move 7 --new-tab

It can also reorder tabs in the active workspace:

artu tab list
artu tab move 3 1

Tab positions are 1-based. A pane move stays inside that pane’s workspace, removes an empty source tab, keeps the process and terminal history alive, and follows the pane with focus. Reordering tabs keeps the same tab active even when its position changes. The skill uses explicit pane IDs and confirmed tab positions instead of inferring either from the visible sidebar.

The skill can also organize workspaces after resolving their stable 0-based indices:

artu workspace list
artu workspace rename 2 "Artuditu website"
artu workspace pin 2
artu workspace unpin 2

Renaming changes only the label. Pinning changes display_position, not the workspace index, and keeps linked worktrees grouped with their parent.

From an external terminal there is no implicit caller pane. The skill resolves live IDs first and uses explicit targets for state changes. It also uses bounded reads and waits, preserves focus where possible, and asks before destructive operations such as closing panes, removing worktrees, merging tasks, or stopping the server.

Inside a managed pane, delegation sends work without waiting by default and keeps the current pane focused. When a result must return asynchronously, the sender can name itself and ask the worker to report back through agent send.

How agent readiness works

Artuditu reports agent identity separately from lifecycle status. Once a pane is recognized as Codex, the skill considers idle, done, working, and blocked ready states. An idle or completed agent is ready for a stable name and a new prompt, so the skill does not wait for it to become working first.

For new agents, the skill prefers agent start, which launches, recognizes, and names the agent with one bounded command. wait agent-status is reserved for waiting on a specific lifecycle state after work has been sent.

From an external Codex terminal, agent start --anchor <pane-id> creates the new no-focus sibling beside an explicit pane and completes the launch in one invocation. Omit --down for a right-side split and add it for a split below. On an older installed release without --anchor, the skill uses pane split <pane-id> --no-focus followed by agent start --pane <new-pane-id>. This keeps Cargo and install.sh releases compatible while newer versions use the faster path.

Fast command path

The skill does not run help or ping before every control command. A normal command already proves whether the production server is reachable. It also reuses resolved pane IDs and successful command results instead of immediately listing or reading the same state again.

Delegation calls agent send directly because the server already resolves live names, pane IDs, and unique agent kinds. A successful response returns the pane, agent, name, and status, so the skill does not prepend agent list. It lists agents once only after not_found or ambiguous_target, when live choices are needed to recover safely.

A successful agent start result with ready: true is complete. The skill does not follow it with another status or agent lookup. It waits only when the next requested action depends on a state transition or when you explicitly ask it to wait.

Common pane and agent instructions stay on the direct path. Detailed guidance for UHP, worktrees, orchestration, modules, DIFF, themes, UI, and destructive operations loads only when a request needs it, which keeps normal control prompts lighter.

Refresh or remove

After updating Artuditu, synchronize its version-matched skill and then start a new Codex thread:

artu skill enable

Remove every unchanged Artuditu-managed copy with:

artu skill disable

Disabling the skill does not stop Artuditu or change any session. Artuditu preserves modified files and externally managed installations, including marketplace plugins.