kartalbas/setup-ai-core

**One harness for every AI coding agent, in every repository, on every machine.**
setup-ai-core gives a repository the same rules, the same session start and the same code
intelligence for Claude Code, OpenAI Codex, Google Antigravity, OpenCode, OpenHands, Cursor,
Windsurf, Aider and GitHub Copilot, on Linux; Windows runs it under WSL. A developer installs it once per
machine and runs one command per repository. Nothing of it is ever committed to the repository.
This README is the only documentation. It describes two things and keeps them apart: **what
exists today** (you can run it) and **what is planned** (the concept, not yet built). Every
section says which one it is.
Quick start
Once per machine, on Linux with Bash 3.2+. Windows runs the harness under WSL: open a WSL
distribution and do everything below inside it (section 5.9).
Open a new terminal. doctor has run and named what is missing (git, gh with its login,
Node.js 20, jq); fix that and nothing else.
Per repository:
Or a whole project folder, every repository in it and the folder itself (section 5.8), and then the
agent started in the folder:
**What init does, in this order.** doctor installs what is missing (git, gh, Node.js, jq,
with brew or apt) and the team modes into your agent tools. If the repository's origin is
github.com/ / - , the project harness / -ai-core is cloned beside
the repositories, into / -ai-core, or **created on GitHub, private, from
the skeleton** when it does not exist yet. The repository gets .ai-core/ (rules, configuration, docs), the agent files (AGENTS.md,
.claude/settings.json, opencode.json, ...), the skills of the harness in .claude/skills/
and .agents/skills/, and the agents in .claude/agents/, all listed in .git/info/exclude.
**A block is written into .gitignore, committed and pushed by init itself** (a worktree keeps
it for its own commit). The run ends with a
report of every file it created, refreshed, kept or removed. **ai-core init --dry-run shows that
report and creates nothing**, on GitHub or on disk; run it first.
Update, on the machine:
moves setup-ai-core to its newest release (a tag vX.Y.Z, cut only when the checks are green) and pulls every project harness on this machine; ai-core update --check only asks.
Then, in a repository, ai-core init brings it to that state and reports what changed.
ai-core session-start says when a checkout is behind the harness or a release is available.
Nothing updates by itself.
---
1. The problem and the idea
Every AI coding agent reads its instructions from a different file. Codex and OpenCode read
AGENTS.md. Cursor reads .cursorrules. OpenHands reads a microagent file. Claude Code reads
AGENTS.md or CLAUDE.md, plus .claude/settings.json. Copilot reads
.github/copilot-instructions.md. A team that uses several agents ends up with several copies of
the same rules in every repository, and the copies drift apart.
The idea of this harness:
1. **Rules and tools live in a few places, not in every repository.** This public
repository, **setup-ai-core**, holds what is true for every project. A private **project harness** holds what is
true for one project. Only the knowledge about one repository is specific to that repository.
2. **A checkout gets an assembled copy.** Agents can only read files inside the repository they
are started in, so the harness copies the assembled result into .ai-core/ of every checkout.
3. **Git never sees that copy.** The harness registers every file it deploys in the clone's own
exclude file (.git/info/exclude). git status stays clean. The repository's history is never
touched.
4. **Everything is automated.** Prerequisites are checked and installed. Skills are deployed, not
installed by hand. Maps of repositories are generated. A rule change reaches every checkout at
the next session.
---
2. What exists today and what is planned
| Part | Today | Planned |
| :--- | :--- | :--- |
| Install the harness into a checkout with one command | yes: ai-core init, after a one-time install per machine; ai-core init --all for every repository under a folder | same |
| Nothing is committed to the repository | yes: a block in the project's .gitignore names every agent file, and .git/info/exclude carries the rest per clone | same |
| Rules for every project | yes: one file per section under rules/, assembled into one rules.md per checkout | same |
| Rules of one project (private harness) | yes: github.com/ / -ai-core, found from the repository's origin, cloned beside the repositories ( / -ai-core), created from a skeleton when missing; its rules/ add or replace sections, its skills/, docs/, data files and repos/ / are assembled into every checkout; a harness may extend another (section 4.5) | same |