director-mode-lite

<h1 align="center">Director Mode Lite</h1>

<p align="center"> <strong>Direct work across Claude Code, Codex CLI, and Grok Build.</strong> </p>

<p align="center"> <a href="https://github.com/claude-world/director-mode-lite/releases"><img src="https://img.shields.io/github/v/release/claude-world/director-mode-lite" alt="GitHub release"></a> <a href="https://github.com/claude-world/director-mode-lite/stargazers"><img src="https://img.shields.io/github/stars/claude-world/director-mode-lite?style=social" alt="GitHub stars"></a> <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="MIT license"></a> </p>

Director Mode Lite is a guidance-first development toolkit. It gives three agentic CLIs a shared operating brief, reusable skills, adapted agents, and a portable way to hand unfinished work to one another.

It adds no permission gates, deny rules, or forced workflow. Claude Code, Codex, and Grok keep their native controls, so users can choose their preferred trusted/full-access mode without Director Mode getting in the way.

Quick start

git clone https://github.com/claude-world/director-mode-lite.git
cd director-mode-lite
./install.sh --cli all /path/to/your-project

Then open the project with any supported CLI:

claude
codex
grok

For the product's full-capability, no-prompt profile, use the installed launcher in a trusted workspace:

.director-mode/bin/director-open claude
.director-mode/bin/director-open codex
.director-mode/bin/director-open grok

It uses each CLI's native open flags—Claude bypassPermissions, Codex

danger-full-access with approvals disabled, and Grok always-approve with its sandbox off. It does not emulate permissions with hooks. Native managed policy can still override the flags, and existing global hooks can still run.

Start with the director-mode skill. When another CLI should continue, use

session-relay.

What gets shared

| Capability | Canonical source | Claude Code | Codex CLI | Grok Build | | --- | --- | --- | --- | --- | | Repository guidance | portable/GUIDANCE.md | CLAUDE.md + .director-mode/ | AGENTS.md + .director-mode/ | reads both | | Skills | skills//SKILL.md | .claude/skills/ | .agents/skills/ | reads Claude-compatible skills | | Agents | agents/.md | .claude/agents/.md | generated .codex/agents/.toml | generated .grok/agents/*.md | | Optional context hook | hooks/advisory.sh | settings.local.json | .codex/hooks.json | none (passive stdout is ignored) | | Session continuity | director-handoff/v2 | new native session | new native session | new native session | | Open launcher | scripts/director-open.sh | native bypass mode | native full-access mode | native always-approve / sandbox off | | Read-only diagnosis | scripts/director-doctor.py | runtime/assets/hooks | runtime/assets/hooks | runtime/assets/hooks |

Grok's Claude compatibility is reused for skills, so the installer does not create a second, conflicting .grok/skills/ tree. Agents receive minimal native adapters because Claude-specific model, tool, and memory frontmatter is not portable across every Grok release.

The operating brief

Before substantial work, keep five things visible:

• Outcome — what should be true at the end.
• Context — the repository facts and prior decisions that matter.
• Constraints — compatibility, scope, time, and user preferences.
• Evidence — tests, build, diff, or inspection that will demonstrate success.
• Next decision — where human judgment adds the most value.

The full guide lives at .director-mode/GUIDANCE.md after installation. It is short by design: permanent instruction files are most useful when they contain only facts needed in every session; detailed procedures belong in skills.

Cross-CLI session relay

Claude, Codex, and Grok each store their own native conversation history. A vendor session ID cannot generally resume in a different vendor's CLI.

Director Mode solves the portable part: it creates JSON and Markdown packets with the goal, current state, decisions, Git snapshot, verification, blockers, and next steps. The receiver starts a new native session and reads the packet.

Leave work for another CLI

.director-mode/bin/director-relay create \
  --from claude \
  --to codex \
  --goal "Finish the authentication refresh" \
  --summary "API behavior is implemented; UI wiring remains" \
  --completed "Added refresh-token rotation" \
  --decision "Kept cookies httpOnly to match the existing threat model" \
  --next "Update the sign-in form" \
  --verification "API unit tests pass"

The relay automatically captures only Git metadata and diff statistics; it does not scan raw transcripts, file contents, or credentials, or serialize the process environment. The packet still contains user-supplied text, paths, and Git filenames. Review those before sharing it outside the workspace; add

--reviewed when you want that review recorded in the packet.

Protocol v2 adds multi-hop lineage (root_id, parent_id, hop, and route) and still validates v1 packets. Chain a Claude → Codex → Grok handoff with:

.director-mode/bin/director-relay create --parent \
  --from codex --to grok \
  --goal "Finish the authentication refresh" \
  --summary "Codex completed UI wiring; integration tests remain" \
  --next "Run the browser integration suite"

Continue the latest packet

# Print a copyable interactive command
.director-mode/bin/director-relay continue --to codex

# Launch only when that is what you want
.director-mode/bin/director-relay continue --to codex --run

# Use a one-shot receiving session
.director-mode/bin/director-relay continue --to grok --headless --run

Other relay commands:

.director-mode/bin/director-relay validate
.director-mode/bin/director-relay status --json
.director-mode/bin/director-relay show
.director-mode/bin/director-relay list

status compares the captured branch, HEAD, Git status, and diff statistics to the live worktree without blocking continuation. When --run is selected, the receiver starts in the caller's live project root; a packet's old workspace path is never trusted as an execution directory.

For same-provider history, keep the provider's native resume flow: Claude Code uses --continue / --resume, Codex uses resume / exec resume, and Grok uses --continue / --resume. Cross-provider work always starts a new native session with the portable packet.

Grok Build also provides grok import for Claude Code sessions. That is a helpful Claude→Grok shortcut; the portable packet remains the three-way format.

Agents, skills, and hooks

Agents

The 14 Markdown agents are the source representation. During installation, Director Mode:

• installs Markdown agents for Claude Code;
• converts each agent to Codex TOML with name, description, and

developer_instructions;

• generates a minimal Grok Markdown adapter with the shared description and

role body, leaving Claude-only runtime controls behind.

This adapts the interface without claiming that tool names, models, or runtime permissions are identical across vendors.

Skills

The repository ships 35 skills, including 31 user-invocable workflows. The cross-CLI entry points are:

• director-mode — create a concise brief and verification contract;
• session-relay — leave or receive portable task state;
• handoff-claude, handoff-codex, handoff-grok — target-specific guidance;
• interop-router — suggest a useful next CLI without auto-executing it.

The established workflow, planning, testing, review, debugging, documentation, and project-health skills remain available. CLI-specific surfaces are described inside the relevant skill instead of being hidden behind a universal claim.

Hooks

The default is none: session relay, skills, agents, and guidance need no hook. Optional --hooks guide adds useful SessionStart context only for Claude Code and Codex. Grok loads guidance through AGENTS.md; current Grok releases ignore passive SessionStart stdout, so installing that adapter would add work without adding context. The optional shared executable:

• consumes the native hook input;
• always exits successfully;
• never returns deny, block, or a permission decision;
• never launches another CLI.

Hooks are independent of permission mode. In particular, Claude hooks may also surface in Grok through its compatibility layer. Audit existing user-level hooks before calling an environment zero-interference.

./install.sh --update --hooks none is also the migration path: it surgically removes Director-owned registrations and unmodified hook assets while preserving custom hooks and locally modified files. The zero-hook verifier checks this state instead of assuming it.

Ownership matching is exact: product-local .director-mode/... commands are matched by their full asset path, while generic legacy .claude/hooks/... names are removed only when the ownership inventory proves Director installed them. A pre-existing, unowned same-name hook is preserved; automation mode warns about the conflict instead of claiming or overwriting it.

Project hooks may require native trust or approval in Codex and Grok. Review the generated config with the CLI's own hook inspection UI.

Installer

./install.sh [--update] [--wizard]
             [--cli all|claude|codex|grok]
             [--hooks guide|none|automation]
             [target-directory]

Common choices:

# Recommended: all adapters; register no Director Mode hooks
./install.sh --cli all --hooks none /path/to/project

# Add non-blocking SessionStart context for Claude and Codex
./install.sh --cli all --hooks guide /path/to/project

# Refresh files and migrate to zero Director-owned hooks
./install.sh --update --cli all --hooks none /path/to/project

# Interactive setup
./install.sh --wizard /path/to/project

The installer backs up an existing .claude/ directory, preserves an existing project guide, and updates only its marked guidance block. Existing Codex hook JSON is merged rather than replaced. Updates merge shipped skill files while preserving extra user files in the skill directories.

Always choose the hook mode explicitly during an update. --hooks none removes Director-owned hook registrations and unmodified owned hook assets;

guide and automation install or refresh those opt-in surfaces. Hooks owned by the project, user, or another plugin remain native CLI configuration.

Before writing managed files, the installer rejects symlinked destination components and final files with multiple hard links. It stops with an error instead of following a managed path to another location or inode.

Optional legacy automation

Version 2 defaults to zero-hook guidance. The previous Claude-only Auto-Loop, changelog, validator, and evolving-loop hook files are not installed or registered unless you explicitly choose:

./install.sh --hooks automation /path/to/project

This legacy mode is separate from the portable three-CLI layer. Its Stop-hook continuation behavior is Claude-specific and is not presented as a universal control mechanism.

Plugin installs

The repository retains a Claude Code marketplace manifest and adds a Codex plugin manifest. The two core skills bundle their own shared guide, relay, and read-only doctor, so director-mode and session-relay remain functional in a plugin-only install. The shell installer adds the complete project-local surface: generated agents, repository guidance, launchers, and optional hook adapters.

Verify

./tests/run-tests.sh
./scripts/verify-install.sh /path/to/project
python3 scripts/director-relay.py --help
python3 scripts/director-doctor.py --cwd /path/to/project --json --no-probe

In the doctor report, runtime.source identifies the selected project,

user, or bundled plugin runtime. Hook discovery covers project and user Claude/Codex configs plus every discovered Grok hooks/*.json surface. Malformed or shape-invalid files appear under hooks.invalid_surfaces; they are never treated as evidence of a healthy zero-hook state.

Doctor exit status only confirms that the read-only report was generated. A clean runtime requires empty runtime.missing and runtime.issues; a clean hook conclusion requires hooks.known_registrations == 0 and an empty

hooks.invalid_surfaces. Use verify-install.sh when a pass/fail gate is required.

The regression suite covers installer modes, native adapters, advisory hook behavior, exact hook ownership, symlink/hardlink write protection, packet creation/validation, metadata-only Git capture, project/user/plugin diagnosis, invalid hook surfaces, update behavior, and uninstall preservation.

Upgrade from 1.x

git pull
./install.sh --update --cli all --hooks none /path/to/project

The important behavior change is the default: legacy automation is now opt-in. To retire an older Director hook setup while preserving unrelated custom hooks, run the same install command with --update --hooks none (the default is already none; spelling it out makes the migration intent explicit).

See MIGRATION.md and FAQ.md for details.

Learn

• Claude World Director Mode guide
• Director Mode for Codex CLI
• Director Mode for Grok Build
• Examples
• Changelog

Director Mode Lite is a community project from Claude World. It is not an official Anthropic, OpenAI, or xAI product.

License

MIT