augint-opencodex

augint-opencodex manages local Codex and OpenCode repository configuration from a single tracked manifest, .ai-opencodex.json.

The current tool ships a real CLI with:

• ai-opencodex init to create .ai-opencodex.json when needed and create any missing managed files without overwriting existing ones
• ai-opencodex update to merge rendered config into managed files, refresh generated docs and skills, and remove stale managed files
• ai-opencodex doctor to inspect manifest resolution, generated files, local ignore setup, and staged generated artifacts
• a first-pass profile model with augint and gov
• local-only ignore handling through .git/info/exclude

ai-opencodex is the preferred executable name. The published package still keeps ai-codex as a compatibility alias. The old sync workflow is now split into init and update.

Installation

For local development:

uv sync --group dev

Once the package is published, the intended install flows are:

uvx --from augint-opencodex ai-opencodex init
uv tool install augint-opencodex
ai-opencodex init

Manifest

This tool expects a tracked .ai-opencodex.json file in the target repository.

• ai-opencodex init creates the manifest from a bundled template when it is missing.
• ai-opencodex init never overwrites an existing manifest; it warns and skips it.
• ai-opencodex update requires the manifest to already exist.

A generated starter manifest looks like this:

{
  "$schema": "https://svange.github.io/augint-opencodex/ai-opencodex.schema.json",
  "version": 1,
  "profile": "augint",
  "references": [],
  "blocked_paths": [],
  "content_policy": {
    "no_emojis": true,
    "no_ai_mentions": true
  },
  "shell_guardrails": {
    "ask": [],
    "deny": []
  },
  "patterns": {
    "org_python_library": false
  },
  "opencode": {
    "enabled": true,
    "default_model": null,
    "local_provider": {
      "kind": "openai-compatible",
      "name": "ollama",
      "base_url": "http://host.docker.internal:11434/v1"
    },
    "models": [],
    "bedrock": {
      "enabled": false,
      "models": []
    }
  },
  "codex": {
    "provider": "openai",
    "model": null,
    "approval_policy": null,
    "sandbox_mode": null,
    "web_search": null
  }
}

The primary schema lives in schemas/ai-opencodex.schema.json.

OpenCode and Codex manifest fields

The opencode and codex sections let the manifest fully express non-secret local tool configuration:

• opencode.local_provider - OpenAI-compatible local endpoint (for example Ollama) rendered as provider.<name>.options.baseURL in opencode.json
• opencode.default_model - top-level model in opencode.json
• opencode.models - curated catalog attached to the local provider
• opencode.bedrock.enabled / opencode.bedrock.models - toggles the amazon-bedrock provider entry with the listed model IDs
• codex.provider - openai or aws; emitted as a runtime hint in .codex/config.toml
• codex.model, codex.approval_policy, codex.sandbox_mode, codex.web_search - override the defaults carried by the active profile

Commands

Initialize a repository:

uv run ai-opencodex init

Preview initialization without writing:

uv run ai-opencodex init --dry-run

Update managed files from the manifest:

uv run ai-opencodex update

Preview pending updates without writing:

uv run ai-opencodex update --dry-run

Fail if managed files are out of date:

uv run ai-opencodex update --check

Inspect the current repository state:

uv run ai-opencodex doctor

Update semantics

init is create-only:

• creates .ai-opencodex.json if it is missing
• creates any missing managed files
• skips existing files with a warning instead of overwriting them

update is merge-oriented:

• reads .ai-opencodex.json
• merges structured config files such as opencode.json and .codex/config.toml
• refreshes generated markdown and skill files from bundled templates
• lets new managed values win conflicts
• removes stale managed files that are no longer expected

Templates and generated skills

Bundled template assets now live under src/augint_opencodex/templates/ instead of being embedded inline in renderer code.

That includes:

• the manifest starter template
• generated .codex/config.toml and .ai-opencodex.md templates
• the generated opencode.json template shell
• the shared skills README template
• the org Python tooling skill file, including valid YAML frontmatter

Generated files

The current tool manages:

• .ai-opencodex.md
• .codex/config.toml
• opencode.json
• .agents/skills/README.md
• .agents/skills/org-python-tooling/SKILL.md when patterns.org_python_library is enabled

Managed outputs are added to .git/info/exclude by default so target repositories do not need to commit them.

Canonical ownership

There is one source of truth for each managed file and one tool responsible for runtime-only behavior.

Managed files should not be hand-edited unless you intend those edits to be merged or replaced on the next ai-opencodex update.

Runtime ownership (augint-shell)

augint-shell is responsible only for runtime and container behavior:

• bind-mounting .codex/ and opencode.json into the container
• injecting secrets (OPENAI_API_KEY, AWS credentials) at launch time
• selecting Bedrock vs OpenAI auth paths based on the manifest's codex.provider / opencode.bedrock.enabled signals
• CLI launch flags (ai-shell opencode, ai-shell codex)

augint-shell should not ship duplicate template copies of opencode.json or .codex/config.toml, and .ai-shell.yaml should not duplicate the shape of .ai-opencodex.json.

Dogfooding this repo

This repository is set up to dogfood the generated instructions flow without a root AGENTS.md.

1. Keep .ai-opencodex.json tracked in the repo root.
2. Run uv run ai-opencodex update to generate .ai-opencodex.md, .codex/config.toml, and the other local-only artifacts.
3. Start Codex with CODEX_HOME=$(pwd)/.codex codex so Codex uses the generated .codex/config.toml as its home config and discovers .ai-opencodex.md via project_doc_fallback_filenames.

Avoid creating a root AGENTS.md here. Codex checks AGENTS.md before fallback filenames in the same directory, so a root AGENTS.md would shadow .ai-opencodex.md and split Codex from the generated OpenCode instructions.

Development

make install
make test
make format
make typecheck
make build