Metadata-Version: 2.5
Name: codexmgr
Version: 0.5.2
Summary: Manage project-local Codex configuration from reusable templates
Project-URL: Repository, https://github.com/JulianKimmig/codexmgr/
Keywords: agents,cli,codex,configuration,skills
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: textual>=8.2.7
Requires-Dist: tomlkit>=0.15.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=1.4.0; extra == 'dev'
Requires-Dist: pytest>=9.0.3; extra == 'dev'
Description-Content-Type: text/markdown

# codexmgr

`codexmgr` manages reusable Codex project setup. Keep shared `AGENTS.md`
snippets, skills, hooks, custom agents, rule files, packages, and reusable MCP
source files in one manager home, then sync the selected pieces into each
project from `.codex/codexmgr.toml`.

The tool is for people who use Codex in several repositories and do not want to
copy the same agent instructions by hand. When a shared rule changes, update it
once in `$CODEXMGR_HOME` and apply it wherever that project has opted in.

Use `codexmgr` when a project should:

- build `AGENTS.md` from reusable instruction snippets
- share skills, hooks, custom agents, and rule files across repositories
- enable packaged Codex setups made from those reusable pieces
- keep reusable MCP server definitions out of the user-level Codex config
- check whether generated Codex files match the project config
- run `codex` with the project `.codex` directory as its local Codex home

The basic model has three parts:

- `$CODEXMGR_HOME` stores reusable inputs; when unset it defaults to
  `~/.codexmgr`
- `.codex/codexmgr.toml` records what the current project wants to use
- `codexmgr apply` resolves the selected inputs and writes the project files
  Codex reads

## Requirements

- Python 3.11 or newer
- `codex` on `PATH` only when using `codexmgr codex ...`

## Install

Install `codexmgr` as a command-line tool from the Python package. `pipx` is
the recommended persistent install because it keeps the tool isolated from
project environments:

```bash
pipx install codexmgr
```

If you use `uv` for command-line tools:

```bash
uv tool install codexmgr
```

Plain `pip` also works inside an environment you control:

```bash
python -m pip install codexmgr
```

Verify the install:

```bash
codexmgr --help
```

## Quick Start

Start inside the project that should receive Codex configuration.

```bash
codexmgr setup
```

`setup` creates `.codex/`, creates `.codex/codexmgr.toml` if it is missing, and
runs `apply`. Existing project config is preserved. Apply also creates or
refreshes codexmgr's managed block in `.codex/.gitignore`.

Create a reusable `AGENTS.md` snippet in the manager home. This command creates
`$CODEXMGR_HOME/agentsmd/coding.toml` and refuses to overwrite an existing file:

```bash
codexmgr init-template agentsmd coding
```

You can also write the snippet yourself. A snippet is a TOML template whose
tables become Markdown headings in `AGENTS.md`:

```toml
# ~/.codexmgr/agentsmd/coding.toml
[coding]
text = """
- Keep source files focused and small.
- Add tests for behavior changes before implementation.
"""
[coding.debugging]
text = "Prefer lasting regression tests over temporary scripts."
```

Add the snippet to the current project:

```bash
codexmgr agentsmd add coding
```

This updates `.codex/codexmgr.toml`, runs `apply`, writes
`.codex/codexmgr.lock`, and refreshes the managed block in `AGENTS.md`.

Preview or validate a snippet when you want to check it before adding it:

```bash
codexmgr agentsmd show coding
codexmgr agentsmd validate coding
```

Check what the project is using after changes:

```bash
codexmgr status
codexmgr doctor
codexmgr apply --check
```

## Managed Files

The project source of truth is `.codex/codexmgr.toml`. CLI commands edit this
file for you, and you can also edit it by hand when that is clearer.

`apply` resolves the source config and may write or update these managed files:

- `.codex/.gitignore`: preserves manual rules outside its managed block,
  ignores every unknown `.codex` entry by default, and explicitly exposes the
  codexmgr-owned files and directories listed below
- `.codex/codexmgr.lock`: resolved AGENTS.md, agent, skill, hook, rule, and MCP
  state
- `.codex/config.toml`: project-local Codex config, including generated
  `[[skills.config]]` entries and `[mcp_servers.<id>]` server definitions
- `.codex/hooks.json`: generated hook config for enabled reusable hook bundles
- `.codex/hooks/<name>`: copied support files for enabled hook bundles
- `.codex/agents/<name>.toml`: copied custom-agent definitions
- `.agents/skills/<name>`: copied manager-home skills
- `.rules/<path>`: copied reusable rule files
- `.guides/<path>`: copied reusable guide documents and supporting assets
- `AGENTS.md`: project instructions with only the generated block replaced

The managed `AGENTS.md` block is:

```markdown
<!-- BEGIN CODEXMGR GENERATED -->
<!-- END CODEXMGR GENERATED -->
```

Manual content outside this block is preserved. If the block is missing,
`codexmgr` appends it. If `AGENTS.md` is missing, `codexmgr` creates it.

Known managed, source-backed skill files, reusable rule files, custom-agent
TOML files, and hook support files receive additional local-edit protection. If
one differs from its reusable source, interactive apply asks whether to keep
the local file for this run, overwrite it from the source, update the shared
source from the local file, or abort. Keeping local is temporary and prompts
again on the next apply. Updating a source warns that other projects may share
it and validates the local content when that resource has a validator.

Generated and composed outputs do not use these choices: the managed
`AGENTS.md` block, `.codex/config.toml`, merged `.codex/hooks.json`,
`.codex/.gitignore`, and `.codex/codexmgr.lock` keep their existing generation
behavior. Extra local files in skill and hook overlay directories remain
untouched. The project-local managed copy conflicts contract records the full
scope and implementation map.

## Project Configuration

`.codex/codexmgr.toml` can opt into each resource type independently. A minimal
file may only contain `[agents_md]`; larger projects can add skills, custom
agents, hooks, reusable rules, and MCP sources or overlays as needed. Package commands
write those same tables rather than a separate package table.

```toml
[agents_md]
src = ["coding", "/absolute/or/project-relative/template.toml"]
[skills]
enabled = ["review-helper"]
disabled = ["experimental-skill", "skills/local-disabled"]
[agents]
enabled = ["rule-retriever"]
disabled = ["experimental-agent"]
[hooks]
enabled = ["repo-rules"]
disabled = ["experimental-hook"]
[rules]
enabled = ["react/", "python/testing.md"]
disabled = ["react/materials/"]
[mcp]
enabled = ["browsermcp"]
[mcp.servers.browsermcp]
enabled = true
bearer_token_env_var = "BROWSERMCP_TOKEN"
env_vars = ["BROWSER_ENV"]
```

Mutating commands run `apply` automatically unless `--no-sync` is passed. If
you edit `.codex/codexmgr.toml` by hand, run `codexmgr apply` or
`codexmgr apply --check` afterwards.

## Reference Resolution

Named `AGENTS.md` snippets resolve from
`$CODEXMGR_HOME/agentsmd/<name>.toml`. Path-like snippet values resolve
relative to the project unless they are absolute paths.

Skills are discovered recursively in the project `.agents/skills`,
`$CODEXMGR_HOME/skills`, and `$CODEX_HOME/skills` stores. Discovery stops at each
directory containing `SKILL.md`, so bundled examples are not separate skills.
Use a unique bare folder name such as `skill1`, or a store-relative reference
such as `set1/skill1`. An exact store-relative match takes precedence over leaf
name matching within that store. Ambiguous references require a qualified
reference or an explicit path to select one source. CLI lists show nested
skills with their store-relative references, and the TUI groups them in a
collapsible folder tree. Both hide duplicate rows for managed project copies
while the source remains available.
The project copy recorded for an enabled `$CODEXMGR_HOME` skill is recognized
as a managed mirror and does not create a false collision on later applies.

To enable or disable all currently known skills under a group, use its
store-relative path with a trailing slash:

```bash
codexmgr skill enable set1/
codexmgr skill disable set1/subgroup/
```

Group commands include all descendant subgroups and save individual skill
references in the project config. Already configured descendants remain included
even if their source is missing. Skills added to the source group later are not
selected automatically. Groups with no discovered or configured descendants
fail before the config is written.

Enabled skills from `$CODEXMGR_HOME` are copied into `.agents/skills/<name>` on
every apply. Group folders organize the source collection; each skill is copied
flat with its contents intact. If the folder name conflicts, codexmgr prefixes
the nearest group using a hyphen: `set1/skill1` can become `set1-skill1`.
Additional ancestor groups are prepended when needed; apply fails if no unique
name is possible. Differing files in a known managed copy use the per-target
conflict choices, while the overlay preserves extra local files.
Existing managed copies retain their assigned names on later applies.
Explicit paths such as `./skills/skill1`, `../skill1`, `~/skills/skill1`, or an
absolute path can point to `SKILL.md` or its containing directory. Relative
paths resolve from the project; a missing explicit path is an error.

Project-local and copied manager-home skills generate portable `name` selectors
using the `name` value in their `SKILL.md` YAML frontmatter. Selected skills in
those stores must therefore have valid frontmatter and a non-empty name. Apply
also fails if two discoverable skills declare the same generated name. Skills
keep their declared YAML names even when copy folders gain a group prefix.
Skills resolved directly from `$CODEX_HOME` and explicit path references keep
absolute `path` selectors because those sources are machine-specific or explicitly
requested. Missing bare names remain name-based entries so Codex can resolve
them later from another installed source.

Managed skill, custom-agent, hook, and rule copy-lock entries use the logical
source `codexmgr_home` and project-relative targets. Apply derives their paths
from the current `$CODEXMGR_HOME` and project root, accepts legacy absolute copy
entries, and rewrites them in portable form. Moving or cloning a project
therefore does not churn generated lock state or direct cleanup into an old
clone. Nested skill copies additionally record `source_path` relative to the
source store's `skills/` directory, independently of the flattened target name.

Named custom agents resolve from `$CODEXMGR_HOME/agents/<name>.toml`. Enabled
agents are copied into `.codex/agents/<name>.toml`; disabled agents remove the
managed copy only when the lock records it as codexmgr-managed.

Named hooks resolve from `$CODEXMGR_HOME/hooks/<name>/hooks.json`. Enabled hook
bundles are merged into `.codex/hooks.json`, and existing unmanaged hooks are
preserved.

Hook bundle files other than the root `hooks.json` are copied into
`.codex/hooks/<name>`. Managed hook handlers receive `codexmanager_meta` so
future applies can distinguish them from local hooks.

Rule refs resolve under `$CODEXMGR_HOME/rules/` and use POSIX-style relative
paths. Folder refs have a trailing slash and copy regular files recursively into
`.rules/` while preserving relative paths.

Rule listings are grouped by folder. `codexmgr rules list` prints an indented
tree, while the TUI Rules screen shows the same refs in a collapsible tree.

File rule refs copy one file. Extensionless refs prefer an existing `<ref>.md`.
Enabled refs expand first, then disabled file or folder refs remove entries from
that candidate set.

First-time rule applies refuse to overwrite unmanaged `.rules/...` files. This
keeps existing project-local rules from being replaced accidentally. The
per-target conflict choices apply after a target is a known managed copy.

## Guides

Guides are reusable documents stored under `$CODEXMGR_HOME/guides/`. Select any
folder depth or an individual file; copies retain their complete relative paths
under the current project's `.guides/` directory. No manifest or frontmatter is
required, and supporting assets are copied byte-for-byte alongside documents.

```bash
codexmgr guides list
codexmgr guides enable games/general
codexmgr guides disable games/general/frameworks
```

The example copies documents into `.guides/games/general/`, including its
`monetization/` subtree, but excludes `frameworks/`. Folder references accept an
optional trailing slash and are saved with `/`. File references use exact names;
there is no implicit `.md` extension.

```toml
[guides]
enabled = ["games/general/"]
disabled = ["games/general/frameworks/"]
```

Folder selectors stay active: later `apply` operations include newly added files
and remove obsolete managed copies. Disabled files and folders override enabled
selections, including parent enables. Enabling a parent again preserves child
exclusions. Missing enabled sources are errors; missing exclusions remain valid.

Existing unmanaged destination files are never overwritten. Changed managed
copies use the normal per-file conflict choices. Cleanup removes only lock-owned
files and empty directories, preserving unrelated project documents. Guide
references must be safe relative paths; symlinks in source or destination guide
paths are rejected. Guides do not inject project instructions or change Codex
configuration. Empty source directories need not be copied. Disabling a guide
removes its managed copy even if edited locally; save those edits elsewhere or
use `update-source` before disabling it.

New files authored inside an enabled project guide folder are discovered on the
next `apply` or TUI save. The same workflow applies to Rules. You can add each
file to its shared store, keep it project-only, or abort. Only files without a
shared counterpart or prior managed-copy ownership are offered, and disabled
files/subfolders are excluded. This happens on apply/save, not through a
background file watcher.

For a new file, **keep project-only** is remembered in the project lockfile's
resource-specific `project_only` list. It remains unmanaged and is not deleted
when the folder is disabled. Remove that file's entry from the list to reconsider
it on the next apply. Adding it to the shared store preserves its relative path
and records managed ownership in the same apply. Neither choice is automatic.

## Packages

Packages are reusable bundles of snippets, agents, hooks, skills, rules, and guides.
They resolve from `$CODEXMGR_HOME/packages/<name>/config.toml`.

A package config is a TOML document with root lists and optional profile tables:

```toml
agentsmd = []
agents = ["rule-retriever"]
hooks = ["repo-rules"]
skills = ["repo-rule-manager"]
rules = ["react/"]
guides = ["games/general/"]
[profiles.strict]
agentsmd = ["strict-coding"]
agents = ["strict-agent"]
hooks = ["strict-rules"]
skills = ["strict-review"]
rules = ["python/testing.md"]
guides = ["games/advanced/performance.md"]
```

The `agents` list enables custom agents from
`$CODEXMGR_HOME/agents/<name>.toml`.

The `skills` list accepts individual skills and store-relative folder groups
ending in `/`, in both the root package and profiles. For example, a Phaser
package can contain:

```toml
skills = ["phaserjs/"]
```

Enabling or disabling the package expands the group recursively and saves each
currently known skill individually. Overlapping groups and individual skill
references select each skill once. New skills added to a group remain available
until you enable the package again. A group with no discovered or configured
descendants fails before the package operation writes project configuration.
The same group behavior applies to TUI package selections and just-in-time
package/profile overlays.

The `guides` list accepts exact files and nested folders in both package roots
and profiles. Unlike skill groups, guide folders remain persistent selectors:
new documents appear on the next apply without re-enabling the package. Guides
also participate in TUI package selection and temporary launch overlays, which
restore the project's guide files when the child process exits.
Guide overlays reject symlinks anywhere in the existing guide target tree before
snapshotting, so unrelated links cannot be changed by restoration.

`codexmgr package enable <name>` validates enabled package sources, then updates
`.codex/codexmgr.toml` as if the corresponding resource commands had been run.

`codexmgr package disable <name>` removes package `AGENTS.md` entries when
present and disables the package skills, hooks, agents, rules, and guides. Package state
is not tracked separately; the resulting project config tables remain the
source of truth.

Profiles are merged with the root package entries:

```bash
codexmgr package enable repo-rules --profile strict python
```

Direct mutating commands also accept batch targets, for example:

```bash
codexmgr agentsmd add coding python
codexmgr skill enable review-helper repo-rule-manager
codexmgr hooks enable repo-rules audit
codexmgr mcp enable browsermcp context7
```

These commands run `apply` automatically unless `--no-sync` is passed.

## Interactive TUI

`codexmgr tui` opens a Textual-based terminal UI for project-local
configuration. It shows `AGENTS.md` snippets, hooks, custom agents, packages,
and reusable MCP sources in selectable lists. Skills, rules, and guides are shown in
collapsible folder trees.

Changes are staged in memory while you navigate. Press `s` to save; the save
writes `.codex/codexmgr.toml` once and runs `apply` once unless `--no-sync` was
used. When apply finds a known managed direct-copy conflict, the TUI offers the
same `keep-local`, `overwrite-local`, `update-source`, and `abort` choices as
the interactive CLI.

For resources with explicit enable and disable lists, `space` cycles the
highlighted row through available, enabled, and disabled states. Package
profiles appear as separate selectable rows under their package. In the Rules
tree, cycling a file or folder node updates the full canonical rule ref behind
that basename label.

Package and profile states reflect the individual skills inside their groups.
Enabling, disabling, or clearing a package row updates those descendants
together; individual skills can still be changed in the Skills tree.

In the Skills tree, press `enter` on a folder to expand or collapse it and
select individual skills inside. Press `space` on a folder to cycle all its
currently listed descendant skills together: available to enabled, enabled
to disabled, and disabled to available. A folder with differing child states
shows `mixed`; pressing `space` enables them all. Expanded folders and the
highlighted skill or group are preserved when cycling or switching sections.
Selections remain staged until you save.

Press `9` for Guides. Enter opens or closes a folder; Space cycles a file or
folder's explicit selector through available, enabled, disabled, and available.
Clearing a selector restores inherited parent behavior. Labels show explicit
selection state, so an available child may still be copied through an enabled
parent. Expanded folders and focus are preserved across selection changes and
section switches.

```bash
codexmgr tui
codexmgr tui --no-sync
codexmgr tui --show-diff
```

The dashboard shows generated-file sync state. By default it lists stale
generated paths; with `--show-diff`, it shows unified diffs for the staged
configuration.

MCP editing in the TUI is intentionally limited to loading and unloading
reusable `$CODEXMGR_HOME/mcp/*.toml` sources. Advanced per-server overlay fields
remain available through the `codexmgr mcp ...` commands or direct
`.codex/codexmgr.toml` edits.

## Template Format

Template files are TOML documents. Each top-level key must be a table and
becomes an AGENTS.md heading. A `text` value inside a table becomes the body
under that heading. Nested tables become nested headings.

```toml
[coding]
text = "Top-level guidance."
[coding.tests]
text = "Test behavior, not implementation details."
```

This example renders a top-level `# coding` section with a nested `## tests`
section below it.

Unsupported scalar entries fail loudly instead of being silently ignored. This
keeps template mistakes visible during `apply`.

## Command Reference

Project lifecycle commands:

```bash
codexmgr setup
codexmgr apply
codexmgr apply --resolve <target-path> <keep-local|overwrite-local|update-source>
codexmgr apply --check
codexmgr apply --diff
codexmgr doctor
codexmgr status
```

`setup` creates `.codex/`, creates `.codex/codexmgr.toml` if missing, then runs
`apply`.

`apply` reads `.codex/codexmgr.toml`, resolves configured sources, writes
managed project files, and refreshes generated state.

For scripts and other noninteractive use, repeat `--resolve` with a target path
and action for every known managed, source-backed copy conflict. For example:

```bash
codexmgr apply \
  --resolve .agents/skills/review/SKILL.md keep-local \
  --resolve .rules/python/testing.md update-source
```

The available actions for existing managed copies are `keep-local`,
`overwrite-local`, and `update-source`. These resolutions apply only to the
current invocation; an unresolved target makes noninteractive apply fail before
writes.

For a newly discovered local Rule or Guide, use `--resolve <target-path>
update-source` to add it to the shared store, or `--resolve <target-path>
keep-local` to remember it as project-only. `overwrite-local` is unavailable
because there is no shared source yet. Interactive apply and TUI save offer
the corresponding choices, including abort. All import and existing-copy
decisions are collected before applying writes.

`apply --check` exits with a failure if generated files are out of sync without
writing them. `apply --diff` also avoids writing and prints unified diffs for
the expected generated-file changes. Both modes remain read-only when a managed
copy differs from its source. A noninteractive `apply` requires an explicit
resolution for each conflicting target and fails before writes when any target
is unresolved.

Checks and diffs also report `Pending import` for new local rules/guides without
prompting or publishing them. Selection commands and TUI saves using `--no-sync`
defer import decisions until an apply.

The `.codex/.gitignore` managed block uses a default-ignore rule rather than a
list of known runtime filenames. New caches, databases, sessions, and other
state created by future Codex versions therefore remain outside Git without a
codexmgr update. Project configuration, custom agents, and hook support files
remain visible to Git.

`doctor` checks project setup, home environment variables, project TOML syntax,
referenced snippets, enabled skills, enabled custom agents, enabled hook
bundles, enabled rules, and stale generated files.

`status` prints the resolved homes, configured snippets, skills, custom agents,
hooks, rules, and whether generated files are in sync.

Manager-home navigation:

```bash
codexmgr cd
codexmgr cd --path
codexmgr cd --explorer
codexmgr cd --terminal
```

`cd` launches a shell in `$CODEXMGR_HOME`. The flags print the path, open a file
explorer, or open a new terminal there.

AGENTS.md snippet commands:

```bash
codexmgr agentsmd list
codexmgr agentsmd show <name-or-template-path>
codexmgr agentsmd validate <name-or-template-path>
codexmgr agentsmd add [--no-sync] <name-or-template-path> [...]
codexmgr agentsmd remove [--no-sync] <name-or-template-path> [...]
codexmgr init-template agentsmd <name>
```

`agentsmd list` prints named templates from `$CODEXMGR_HOME/agentsmd` in sorted
order.

`agentsmd show` renders one template as `AGENTS.md` markdown without changing
project configuration. `agentsmd validate` loads and renders a template to catch
TOML or template-shape errors before adding it.

`agentsmd add` validates that the template exists before writing config.
Repeated adds keep one source entry.

`agentsmd remove` removes configured template sources and fails if a requested
source is not present.

`init-template agentsmd` creates a starter template under
`$CODEXMGR_HOME/agentsmd` and refuses to overwrite an existing template.

Shared resource commands:

```bash
codexmgr skill list
codexmgr skill enable [--no-sync] <skill-ref> [...]
codexmgr skill disable [--no-sync] <skill-ref> [...]
codexmgr agents list
codexmgr agents enable [--no-sync] <agent-name> [...]
codexmgr agents disable [--no-sync] <agent-name> [...]
codexmgr hooks list
codexmgr hooks enable [--no-sync] <hook-name> [...]
codexmgr hooks disable [--no-sync] <hook-name> [...]
codexmgr rules list
codexmgr rules enable [--no-sync] <rule-ref> [...]
codexmgr rules disable [--no-sync] <rule-ref> [...]
codexmgr guides list
codexmgr guides enable [--no-sync] <guide-ref> [...]
codexmgr guides disable [--no-sync] <guide-ref> [...]
```

`skill list`, `agents list`, and `hooks list` print available resources and
mark configured entries as enabled, disabled, or missing. `rules list` and `guides list` print
the same state in an indented folder hierarchy.

A `skill-ref` is a skill name, explicit skill path, or store-relative group
path ending in `/`.

Enable commands validate manager-home sources when the source type must already
exist. Enable and disable lists stay mutually exclusive, and repeated commands
keep one entry.

Rules and guides have one exception to exact mutual exclusion: a parent folder enable and a
child file or folder disable can intentionally coexist.

Package commands:

```bash
codexmgr package list
codexmgr package enable [--no-sync] <package-name> [...] [--profile <name> [...]]
codexmgr package disable [--no-sync] <package-name> [...] [--profile <name> [...]]
```

`package list` prints available `$CODEXMGR_HOME/packages/*/config.toml` entries
in sorted order.

`package enable` and `package disable` proxy to the underlying AGENTS.md,
custom-agent, skill, hook, and rule project-config mutations.

Codex wrapper command:

```bash
codexmgr codex <args...>
codexmgr codex --simple <args...>
```

By default, `codexmgr codex` applies the current project config, launches the
real `codex` command with `CODEX_HOME` set to
`<project>/.codex/.runtime`, and forwards Codex arguments unchanged. For a
trusted project, Codex discovers the tracked `.codex/config.toml` as its
project configuration independently of `CODEX_HOME`. This keeps generated MCP
servers and other shared project settings in Git while mutable Codex state is
written below the ignored `.codex/.runtime` directory. User-provided `-c` and
`--config` arguments retain their normal Codex behavior.

The wrapper links the global authentication file into
`.codex/.runtime/auth.json`. It uses `CODEX_GLOBAL_AUTH` when that variable is
non-empty and otherwise uses `$HOME/.codex/auth.json`. A missing auth source
produces a warning but does not stop Codex, which can then authenticate within
the project runtime home.

Use `--simple` immediately after `codex` to run the basic command without
applying project state, changing the child `CODEX_HOME`, or managing an auth
link. This launch wrapper is intentionally CLI-only because the TUI does not
embed or proxy external terminal sessions.

The wrapper can run with a just-in-time package/profile overlay without changing
`.codex/codexmgr.toml`. Put Codex arguments after `--` when using this syntax:

```bash
codexmgr codex --package repo-rules --profile strict python -- exec "review this"
```

## Project MCP Sources

`codexmgr mcp ...` loads reusable MCP definitions from `$CODEXMGR_HOME/mcp`
into project-local configuration:

- reusable source state is stored in `.codex/codexmgr.toml` under `[mcp]`
- per-project server overlays are stored under `[mcp.servers.<id>]`
- `apply` writes generated server definitions into `.codex/config.toml` under
  `[mcp_servers.<id>]`
- `$CODEX_HOME/config.toml` and `~/.codex/config.toml` are never modified

Mutating MCP commands require a project `.codex/` directory and run `apply`
automatically unless `--no-sync` is passed.

Create reusable source files in the same `mcp_servers` shape Codex reads from
`config.toml`:

```toml
# ~/.codexmgr/mcp/browsermcp.toml
[mcp_servers.browsermcp]
command = "browsermcp"
args = ["--port", "3000"]
env_vars = ["BROWSERMCP_TOKEN"]
```

List reusable sources and show project state:

```bash
codexmgr mcp list
codexmgr mcp show browsermcp
codexmgr mcp validate
```

Enable or disable reusable sources for the current project:

```bash
codexmgr mcp enable browsermcp context7
codexmgr mcp disable browsermcp
```

`disable` unloads the source from `[mcp].enabled`. It does not keep a generated
server definition with `enabled = false`.

Use `[mcp.servers.<id>]` for project-local overlays. Overlays merge after source
files, so they can override or add fields:

```toml
[mcp]
enabled = ["browsermcp"]

[mcp.servers.browsermcp]
enabled = false
bearer_token_env_var = "BROWSERMCP_TOKEN"
```

Update common token and environment references from the CLI:

```bash
codexmgr mcp set-token-env figma FIGMA_TOKEN
codexmgr mcp add-env-var context7 CONTEXT7_TOKEN
codexmgr mcp remove-env-var context7 CONTEXT7_TOKEN
codexmgr mcp set-env-header figma Authorization FIGMA_AUTH_HEADER
codexmgr mcp unset-env-header figma Authorization
```

Set a small allowlist of overlay fields from TOML literals:

```bash
codexmgr mcp set-field context7 required true
codexmgr mcp set-field context7 enabled_tools '["search", "open"]'
codexmgr mcp set-field context7 default_tools_approval_mode '"prompt"'
```

Supported `set-field` names are `required`, `startup_timeout_sec`,
`tool_timeout_sec`, `enabled_tools`, `disabled_tools`, and
`default_tools_approval_mode`.

Source files and hand-written overlays can use the full Codex `mcp_servers`
shape. Prefer environment variable references such as `bearer_token_env_var`,
`env_vars`, and `env_http_headers` for secrets.

## Development

Use a checkout when developing `codexmgr` itself.

Install dependencies:

```bash
uv sync --group dev
```

Run tests:

```bash
uv run pytest
```

Build distributions:

```bash
uv build
```

The package is typed (`py.typed`) and the test suite covers CLI behavior,
template rendering, TOML writing, skill resolution, generated-file sync checks,
Codex command generation, home-directory resolution, and package metadata.
