Local AI Agent Setup

This guide defines how MIDDAG repositories should handle local AI agents and plugins. These files are usually runtime state, per-developer installs, or tool caches, so they belong in .gitignore.

Policy

• Do not commit local agent state.
• Do not commit logs, sessions, caches, keys, or personal settings.
• Do not copy tool directories from one developer to another.
• Commit shared configuration only when the project explicitly decides to do so.
• Document a tool in the repository when it is required for development, testing, or publication.

Known tools

Tool	Typical use	Ignore in Git
AIOX	Local agent install/runtime through aiox-core.	.aiox-core/, .aiox-core/local/, .aiox/install-log.txt
Ralph	Agent/plugin session state, counters, logs, and progress.	.ralph/.call_count, .ralph/logs/, .ralph/status.json, .ralph/docs/generated/
GStack	Local orchestration or agent stack state.	.gstack/
Caveman	Local skill/agent install for the developer environment.	.agents/, .claude/skills/, skills-lock.json
Claude/Codex local	Machine-specific preferences, skills, and local settings.	.claude/settings.local.json, .claude/skills/

Recommended setup

1. Install the tool using the official project or plugin method.
2. Run repository-local installation only when the tool requires local state.
3. Check git status --short after installation.
4. If new runtime, cache, or session files appear, add the rule to .gitignore before continuing.
5. If a generated configuration file looks useful for the whole team, validate it before committing.

AIOX

When a repository uses AIOX, local installation may create .aiox-core/, .aiox-core/local/, and .aiox/install-log.txt. These files are developer-specific and should not be committed.

npx aiox-core install

Ralph

Ralph generates session, progress, log, and execution-control files. They support local tooling but are not approved code, documentation, or shared configuration.

If a Ralph-generated artifact is useful as documentation, move the reviewed content to docs/ or docs-site/ instead of committing .ralph/docs/generated/.

GStack

Treat .gstack/ as local orchestration state. Do not use this directory as the source of project operational configuration.

Caveman, Claude, and local skills

Skills installed in .claude/skills/ or .agents/ are local installs. To standardize a skill for the team, document the requirement in the project guide and prefer an installable source or clear setup procedure instead of committing the whole local installation.

When to commit something

Commit a file only when it is:

• required for build, test, lint, or deploy;
• safe to publish in the repository;
• stable across machines;
• reviewed as shared configuration.

When in doubt, keep it local and record the decision in a guide or ADR.