Codebat

Drop-in tooling that makes a repository ready for AI coding agents.

Codebat is a lightweight, Windows-first launcher/bootstrap layer. Add it as a Git submodule directly inside your project. Collaborators can then launch OpenCode or Pi without manually installing each agent or a global Codebat CLI. Node.js and npm are still required; agent credentials are configured by users through the agents themselves.

Quick Start

For the easiest start, open the Codebat folder and double-click codebat.bat, then select an agent.

The menu lists the agents by name. Enter a number to launch, or Q to quit. Invalid selections let you try again. Startup errors wait for acknowledgement; successful agent launches do not add a pause.

From your project's root in Windows Command Prompt:

git submodule add https://github.com/Geonhui-Lee/codebat.git codebat
git commit -m "chore: add Codebat submodule"
codebat\codebat.bat opencode

Or launch Pi:

codebat\codebat.bat pi

List agents or forward arguments:

codebat\codebat.bat list
codebat\codebat.bat opencode --help
codebat\codebat.bat pi --version

Inside the Codebat directory, the equivalent commands are codebat opencode and codebat pi. No PATH changes or global Codebat installation are needed. Running codebat without arguments opens the same menu. Unknown commands print help and return a nonzero exit code; codebat --help and codebat -h print help successfully. Explicit commands do not pause on errors.

Important

Keep Codebat directly inside the project root. Its immediate parent is always the agent's working directory, regardless of where you invoke the launcher. my-project\tools\codebat would target tools, not my-project. Paths containing spaces are supported; quote the launcher path when needed.

Prerequisites

• Windows and Node.js with npm on PATH (a currently supported LTS is recommended).
• Pi specifically requires Node.js 22.19.0 or newer. This check does not block OpenCode; OpenCode's own upstream requirements still apply.
• Git for Windows; Pi uses its bundled Git Bash by default.
• Internet access for the first installation of each agent.

No root npm install is necessary. The selected agent installs automatically on first launch. Later launches validate and reuse its local installation.

Collaborator Setup

For a new clone:

git clone --recurse-submodules <repository-url>
cd <repository-directory>
git config --local submodule.recurse true

For an existing clone, run from the project root:

git submodule update --init --recursive
git config --local submodule.recurse true

Then double-click codebat.bat inside the Codebat folder, or use codebat\codebat.bat opencode or codebat\codebat.bat pi from Command Prompt. Each collaborator has their own ignored installation and agent state. The recursive Git setting is local to each clone, so each collaborator must set it themselves. With this setting, normal git pull updates Codebat to the commit recorded by the parent project. If needed, follow a pull with git submodule update --init --recursive explicitly.

Supported Agents

Agent	Direct command	Compatibility wrapper	npm package
OpenCode	codebat\codebat.bat opencode	_opencode.bat	opencode-ai
Pi Coding Agent	codebat\codebat.bat pi	_pi.bat	@earendil-works/pi-coding-agent

Use codebat.bat for File Explorer's interactive menu. The existing _opencode.bat and _pi.bat remain thin compatibility wrappers. They forward arguments and return the agent's exit code without pausing on errors.

Architecture and Isolation

codebat/
├─ codebat.bat             # primary entry point
├─ _opencode.bat           # compatibility wrapper
├─ _pi.bat                 # compatibility wrapper
├─ agents.json             # packages, versions and agent-specific requirements
├─ lib/
│  ├─ codebat.cjs           # shared bootstrap and launch logic
│  └─ install.bat           # small Windows npm bridge
├─ runtime/                # generated, ignored
│  ├─ opencode/            # own package.json, lockfile, node_modules, npm cache
│  └─ pi/                  # own package.json, lockfile, node_modules, npm cache
├─ .opencode/              # existing project-local OpenCode user state
└─ .pi/agent/              # existing project-local Pi user state

Each runtime is a private npm project. Installing Pi cannot modify OpenCode's dependency tree or require repairing it, and vice versa. Nothing installs into the root node_modules or the parent project's dependency environment. The root package.json only provides dependency-free maintainer tests.

The shared helper:

1. Resolves Codebat and its immediate parent workspace.
2. Checks Node/npm and the selected agent's additional requirements.
3. Checks the configured package version, executable, and --version response.
4. Installs missing, mismatched or broken packages in that agent's runtime.
5. Validates the installation with visible diagnostics.
6. Executes the agent in the parent directory and returns its exit code.

Both installations use npm install --save-exact --ignore-scripts. Only OpenCode runs npm rebuild opencode-ai for its required installation step; Pi's dependency lifecycle scripts remain disabled. npm installation/rebuild output is not suppressed.

Top-level package versions are pinned in agents.json to the existing supported versions. Changing a pin causes that agent to reinstall on its next launch. Each collaborator's generated lockfile records their resolved dependencies; transitive dependencies are not centrally locked by Codebat.

A small Node helper replaces duplicated batch installation logic and avoids re-parsing agent arguments through cmd.exe. It reads npm package bin metadata and launches native .exe entries directly or JavaScript entries with Node. Node was already a prerequisite; the helper adds no dependencies. Only npm installation uses the batch bridge.

Project-local State

OpenCode receives XDG_CONFIG_HOME, XDG_DATA_HOME, XDG_CACHE_HOME, and XDG_STATE_HOME under codebat\.opencode. Pi receives PI_CODING_AGENT_DIR=codebat\.pi\agent. Existing state directories are preserved so upgrading does not discard configuration or credentials. Each agent's npm cache also stays in its own runtime.

runtime/, .opencode/, .pi/, and legacy node_modules/ are ignored by Git. Do not commit credentials or runtime files. This is state redirection, not a sandbox: agents can still read project configuration, use external tools, and create project files. Explicit upstream configuration or third-party tools may use other locations; Codebat does not replace the user's home directory.

Upgrading from the Shared Runtime

The old root node_modules and package lock are no longer used for launching. The first v0.2.0 launch installs each selected agent in its isolated runtime. Existing .opencode / .pi state remains in place. After verifying the new launchers, you may remove the unused root node_modules yourself. Codebat does not delete or migrate that directory automatically.

Updating the Submodule

Collaborators normally follow the Codebat commit pinned by their parent project, rather than independently upgrading it.

Project maintainers can intentionally select a newer Codebat commit:

git submodule update --remote codebat
git add codebat
git commit -m "chore: update Codebat submodule"

Review/test the new commit before committing the updated submodule pointer. Collaborators receive that pointer through normal project updates.

Troubleshooting

Missing Node.js/npm or an unsupported Pi version

Install Node.js with npm, open a new Command Prompt, and check node --version and npm --version. Pi requires at least 22.19.0.

Installation or validation fails

Read the npm or agent output, check internet/proxy access, and retry. To diagnose an existing runtime manually from the project root:

cd codebat\runtime\opencode
npm install --save-exact --ignore-scripts opencode-ai@1.18.29
npm rebuild opencode-ai

For Pi, use its separate runtime and do not rebuild OpenCode:

cd codebat\runtime\pi
npm install --save-exact --ignore-scripts @earendil-works/pi-coding-agent@0.85.0

If the runtime is corrupt, close that agent and remove only its codebat\runtime\<agent> directory, then relaunch. Keep .opencode and .pi unless you intentionally want to reset user state.

Wrong workspace or missing Codebat

Place the submodule directly inside the intended project. Initialize a missing submodule with git submodule update --init --recursive from the project root. Launching the standalone Codebat repository targets its parent, not Codebat.

Development and Tests

From the Codebat repository:

npm test
git diff --check

Tests use Node's built-in test runner, temporary directories and mock agents/npm. They do not download agents. Shared-logic tests cover dispatch, quoting-sensitive arguments, workspace resolution, state, isolated installations, validation, agent-specific Node requirements, native/JavaScript execution and exit codes. Windows-only tests exercise the actual .bat entry points and missing Node/npm handling, menu selection/retry/quit and interactive error acknowledgement. GitHub Actions runs the full suite on Windows with Node 22.19.0 and 24. Non-Windows hosts can run shared-logic tests, but batch tests are skipped; agent launching itself remains Windows-only.

To add a future compatible npm-based agent, add its package/version/bin, local state mapping and any minimum Node requirement to agents.json. Add a thin root _<agent>.bat wrapper if useful, extend tests, and update this README. No separate dependency framework or duplicated installer is needed.