AkiForge — Portable Agent Harness

AkiForge is a portable, terminal-first harness engine for Codex and OpenCode. It gives coding agents the project-specific rules, runtime boundaries, and verification commands they need without loading an entire handbook into every conversation. One committed project profile works across both platforms, while the globally installed engine supplies reusable policy, adapters, upgrade planning, structured results, and an optional local dashboard.

What AkiForge can do

• Detect a project stack and create a reviewed runtime profile for host or Docker Compose execution.
• Keep agent context small by loading security, frontend, backend, database, testing, deployment, and review rules only when relevant.
• Route tiny, normal, and high-risk work through appropriately strict implementation and review workflows.
• Enforce approval boundaries for dependencies, migrations, destructive data, deployment, credentials, Git publication, and other sensitive operations.
• Run preflight and application checks in the configured environment and report PASS, PASS_WITH_GAPS, FAIL, or INCOMPLETE truthfully.
• Generate deterministic Codex and OpenCode adapters from one canonical policy.
• Initialize a thin project contract, adopt supported legacy installations, and preview or apply contained project upgrades with conflict preservation.
• Bridge a supported 0.1 thin contract to the 0.2 contract through a packaged, reviewed, atomic migration with explicit rollback.
• Update or downgrade the global engine independently from project files.
• Recognize declared external tools and report bounded readiness facts without installing, updating, executing, or certifying them.
• Return stable text and JSON results, expose an optional token-protected read-only localhost API, and visualize project state in an optional dashboard.

AkiForge does not replace Codex or OpenCode chat, install missing project tools, start containers, run migrations, deploy, read credentials, or repair a runtime without explicit authorization.

Core idea

global AkiForge engine
    +--> canonical policy, schemas, adapters, runtime, verification
    +--> CLI / JSON / local API / dashboard share typed services
                    |
                    v
thin committed project contract
    +--> AGENTS.md
    +--> .harness/project.json
    +--> .harness/lock.json
    +--> selected generated Codex/OpenCode adapters

Tiny changes should remain tiny. High-risk work can escalate to planning, independent review, full verification, security checks, and rollback notes.

Install and initialize

Install the engine once. uv tool is preferred; pipx is supported:

uv tool install akiforge
akiforge --version
akiforge resource-health

Preview a thin contract for a new repository, apply it only after review, then check the configured runtime and application:

akiforge --project /path/to/project init --profile all --check
akiforge --project /path/to/project init --profile all --apply
akiforge --project /path/to/project adapter validate
akiforge --project /path/to/project codex configure --check
akiforge --project /path/to/project codex configure --apply
akiforge --project /path/to/project project preflight
akiforge --project /path/to/project verify targeted

Use --profile codex, --profile opencode, or --profile all for one or both platforms. Codex hooks remain inactive until the explicit configuration apply. Review and commit the managed contract plus .harness/project.json; do not edit generated .harness/lock.json manually.

The official lifecycle is:

install -> init -> review profile -> preflight -> verify
        -> update engine independently -> preview/apply project upgrade or migration

Existing vendored projects use project adopt, never a fresh sync:

akiforge --project /path/to/legacy-project project adopt --check
akiforge --project /path/to/legacy-project project adopt --apply

See the complete guide, installation, project initialization, engine update, legacy adoption, project migration, and rollback. The public package and maintainer publication boundaries are in Public Distribution and the release runbook. Legacy command boundaries are in Command Migration. Ownership and supported customization are defined in Customization, with the engine/contract matrix in Compatibility and failure semantics in Runtime Resilience. External-tool ownership and readiness are in External Tool Readiness, with the Graphify-specific workflow.

The public package exposes its Python source and bundled resources. The repository currently grants no public software license; the package metadata states that explicitly. Publishing authority belongs to the protected release workflow and PyPI Trusted Publishing, not to package secrecy.

Main commands

External-tool commands report readiness, not compatibility. They never install or update the tool, execute its native workflow, parse its output, or claim an artifact is correct or fresh. See External Tool Readiness before adding the optional .harness/external-tools.json declaration.

Optional local dashboard

Start the dashboard for one explicit project:

akiforge --project /path/to/project dashboard

Open the exact token-bearing URL printed in the terminal. The dashboard shows:

• the active project, runtime probes, gaps, and manual checks;
• the latest valid verification report;
• engine, contract, profile-schema, and adapter status;
• the current project-upgrade plan and conflict list.

Read views do not write the project. Upgrade apply requires review of the exact plan and an explicit checkbox; stale plans are rejected. Local conflict files are preserved while packaged candidates are staged under .harness/incoming. Every dashboard action has a CLI equivalent, and stopping or removing the dashboard does not affect the engine or project contract.

There is no remote mode, CORS, chat, shell, credential store, generic file browser, or background mutation. See Optional local dashboard for usage, security controls, keyboard navigation, troubleshooting, and manual test steps.

Missing tools are blockers

AkiForge does not search Windows, /mnt/c, sibling drives, or unrelated global installations when a required project command is unavailable.

For a host runtime, commands such as PHP, Composer, or Node must exist on that host. For a Docker Compose runtime, they must exist inside the configured application service. A failed preflight or required verification probe returns a nonzero result and identifies the exact runtime and missing command.

The agent must then ask the user whether to:

• install the command manually;
• start or rebuild the configured service;
• select a different Compose service;
• intentionally change the project runtime profile.

The harness never installs tools or changes images automatically.

Verification results

Application verification writes .harness/reports/last-verification.json and reports:

• PASS: every required configured check ran and passed;
• PASS_WITH_GAPS: required checks passed, with visible optional gaps;
• FAIL: an executed check failed;
• INCOMPLETE: a required check or runtime command could not run.

Repository maintainers use just validate to validate AkiForge itself. It is not a new-project command or proof that application checks passed.

Codex compatibility

Codex uses AGENTS.md, generated .codex/agents/*.toml, compatible skills, native command rules, and optional hooks. Activate the installed hooks only through the preview/apply workflow in Codex configuration.

The PreToolUse hook contract remains intentionally narrow:

• return {} for unmatched, safe, and approval-required commands;
• return permissionDecision: "deny" only for forbidden commands or policy failures;
• let generated native Codex rules own approval prompts.

Do not introduce permissionDecision: "ask", or a pass-through allow response without a valid input rewrite. Docker Compose and Laravel Sail wrappers are normalized before policy matching so wrapped migrations and dependency changes keep the same prompt requirements.

OpenCode compatibility

OpenCode uses AGENTS.md, opencode.jsonc, and generated .opencode/ adapters. Runtime detection and enforcement remain shared Python behavior rather than a platform-specific OpenCode hook.

OpenCode native permissions continue to handle allow, ask, and deny decisions. Generated adapter files must not be edited directly; maintainers change packaged canonical inputs, while projects regenerate through akiforge adapter generate.

Workflow routing

• Tiny: one or two local files, no API/schema/auth/deployment impact. Inspect, edit, run targeted verification, report.
• Normal: several related files or reversible behavior. Use a compact plan, implement, run targeted checks, review the diff, report.
• High risk: auth, permissions, secrets, uploads, payments, migrations, data deletion, deployment, production config, or broad architecture. Use full planning, relevant rules, independent review, full verification, and rollback notes.

Per-invocation approval remains required for dependency changes, Git publication/history operations, file deletion, migrations, deployments, credential access, production operations, and destructive data operations—even when wrapped by Docker or Sail.

Context rules

Always loaded:

• AGENTS.md;
• the current request;
• the current role or workflow instructions.

Loaded only when relevant:

• harness/rules/frontend.md;
• harness/rules/backend.md;
• harness/rules/security.md;
• harness/rules/database.md;
• harness/rules/deployment.md;
• harness/rules/testing.md;
• harness/rules/review.md;
• project-specific architecture and API contracts.

Historical runs, completed tasks, all ADRs, and unrelated domain documentation stay unloaded by default.

Legacy vendored compatibility

just recipes, direct scripts/*.py entry points, and full-project sync remain available only for repositories that already vendor the old harness. They are not the installation path for new projects. Do not prune vendored files during the initial adoption change; prove verification and rollback first.

The exact mapping from every legacy command to the global CLI is in Command Migration. Unsupported legacy-only maintenance commands are labeled there rather than silently redefined.