A project management tool for Claude Code, OpenAI Codex CLI, and other agent CLIs. It deploys AI operation guidelines and document structure (requirements, design, tasks) to a target directory with a single command.
aiprj provides the following features:
- Definition of AI operation guidelines and rules
- Document structure for requirements, design specifications, and task lists
- Slash commands for Claude Code (
/setup_ai/ai/update_ai/next_ai/close_ai) - Codex CLI skills (
$setup-ai$ai$update-ai$next-ai$close-ai) - Automatic work log saving (
.aiprj/AI_LOG/yyyy-MM-dd_NNN.md)
curl -fsSL https://raw.githubusercontent.com/aquaxis/aiprj/main/install.sh | shcurl -fsSL https://raw.githubusercontent.com/aquaxis/aiprj/main/install.sh | sh -s -- <directory_name>git clone https://github.com/aquaxis/aiprj.git
cd aiprj
./install.sh <target_directory>The installer fetches the main branch by default. Set AIPRJ_BRANCH to use another one:
AIPRJ_BRANCH=develop curl -fsSL https://raw.githubusercontent.com/aquaxis/aiprj/main/install.sh | sh| Option | Description |
|---|---|
-u, --uninstall |
Remove aiprj files from the target directory |
-f, --force |
Skip the confirmation prompt (uninstall only) |
-h, --help |
Show the help message |
-V, --version |
Show the version and exit |
The following files are created by setup:
.aiprj/- AI rules,instructions.md,README.md.claude/- Claude Code settings and slash commands.agent-cli/- Equivalent settings and commands for agent CLIs other than Claude Code.agents/skills/- Codex CLI skills wrapping the same five commands ($aietc.).gitignore- Git ignore configuration (prepended to existing file if present, skipped if the entries already exist)
Re-running the installer over an existing installation refreshes the rules and command
definitions, but an existing .aiprj/instructions.md is never overwritten - its current
contents are printed to the console and left in place. The instructions.md.org template is
only renamed to instructions.md when no instructions.md exists yet.
./install.sh -u <target_directory> # asks for confirmation
./install.sh -u <target_directory> --force # no prompt| Items | |
|---|---|
| Removed | .aiprj/ (rules, instructions, work logs, project documents), the five aiprj slash commands under .claude/commands/ and .agent-cli/commands/, the five aiprj Codex skills under .agents/skills/ (.agents/ itself is kept when it still contains your own skills), and aiprj entries in .gitignore |
| Preserved | .claude/settings.json, .claude/settings.local.json, .agent-cli/config.toml, .mcp.json - these may contain your own customizations |
If .gitignore becomes empty after the aiprj entries are removed, the file itself is deleted.
| Command | Description |
|---|---|
/setup_ai |
Create project documents (requirements, design, tasks) |
/ai |
Execute tasks based on instructions.md |
/update_ai |
Update project documents |
/next_ai |
Proceed to next task |
/close_ai |
Save work log and exit |
Each command file is a thin wrapper that @-references its rule under .aiprj/rules/.
Two exceptions: next_ai carries no rule reference (it is just the literal instruction
"Go next job"), and close_ai appends exit so the session itself ends after the log is saved.
The same five operations are also installed as Codex skills
under .agents/skills/, so the Codex CLI finds them automatically when launched in the project
directory (no extra Codex configuration is needed):
| Skill | Codex invocation | Equivalent to |
|---|---|---|
setup-ai |
$setup-ai |
/setup_ai |
ai |
$ai |
/ai |
update-ai |
$update-ai |
/update_ai |
next-ai |
$next-ai |
/next_ai |
close-ai |
$close-ai |
/close_ai |
Type $ in the Codex composer (or run /skills) to invoke a skill explicitly. Each skill's
SKILL.md is a thin wrapper that reads the same rule file under .aiprj/rules/. Because Codex
does not expand Claude Code's @file references, the skills state the semantics inline
("@path means: read that repository-relative file"). Every skill ships an agents/openai.yaml
with allow_implicit_invocation: false, so Codex only invokes it explicitly - the skills
never trigger on their own from unrelated prompts.
Two Codex-specific differences worth noting:
$close-aisaves the work log but does not terminate the CLI (Codex skills cannot exit the process); the skill reminds you to run/exityourself.$next-aicontinues in the same session exactly like/next_ai; the context carries over because the skill is invoked as a prompt within the running chat.
The rule loaded by each command determines which files the AI is permitted to write.
| Command | Rule file | Guidelines applied | Write scope |
|---|---|---|---|
/setup_ai |
rules/setup_project.md |
Operation (Art. 1-8) + Project Specifications (Art. 1-4) | The three project documents only - creating or modifying any other file is prohibited |
/ai |
rules/exec_job.md |
Operation (Art. 1-8) + Coding (Art. 1-3) | Unrestricted (implementation work); AI_PRJ_TASKS.md must be updated on every task status change |
/update_ai |
rules/update_project.md |
Update (Art. 1-4) | The three project documents, plus work logs |
/next_ai |
none | - | Inherits the current session context |
/close_ai |
rules/close_ai.md |
Work-log rule (Art. 1) | Work logs only, then exit |
AI_PRJ_REQUIREMENTS.md, AI_PRJ_DESIGN.md, and AI_PRJ_TASKS.md are treated as a single
consistent set. Both /ai and /update_ai require the AI to detect any inconsistency among the
three documents and resolve it before proceeding with the rest of the work.
The example below builds a small REST API in ~/work/todo-api.
mkdir -p ~/work/todo-api && cd ~/work/todo-api
curl -fsSL https://raw.githubusercontent.com/aquaxis/aiprj/main/install.sh | shaiprj: Setting up project...
Downloading via curl + tar...
aiprj setup complete: .
At this point .aiprj/instructions.md exists but only contains the placeholder text
Write instructions here.
This is the only file you author by hand. It is free-form - write it as you would a brief for a colleague. The more concrete the constraints, the less the AI has to guess.
$EDITOR .aiprj/instructions.md# TODO API
Build a REST API for managing TODO items.
## Functional requirements
- CRUD endpoints for TODO items (create, list, update, delete)
- Each item has: id, title, completed flag, created_at
- Filter the list endpoint by completion state
## Technical constraints
- Node.js + TypeScript + Fastify
- SQLite for persistence (via better-sqlite3)
- Unit tests with vitest, minimum 80% coverage
- No authentication in the first iterationclaude
> /setup_ai
The AI reads instructions.md and creates three documents. During this command it is only
allowed to write those three files - it will not touch your source tree yet.
.aiprj/
├── instructions.md # what you wrote in step 2
├── AI_PRJ_REQUIREMENTS.md # created: functional / non-functional requirements
├── AI_PRJ_DESIGN.md # created: endpoints, schema, module layout
└── AI_PRJ_TASKS.md # created: the ordered task list
AI_PRJ_TASKS.md typically comes out looking like this:
| # | Task | Status |
|---|------|--------|
| 1 | Set up the project (package.json, tsconfig, vitest) | Not started |
| 2 | Define the SQLite schema and migrations | Not started |
| 3 | Implement the TODO repository layer | Not started |
| 4 | Implement the CRUD endpoints | Not started |
| 5 | Add the completion-state filter | Not started |
| 6 | Write unit tests to 80% coverage | Not started |Review the three documents before continuing. They are the contract every later command works from - correcting a misunderstanding here is far cheaper than correcting it after implementation.
> /ai
Unlike /setup_ai, this command may write anywhere in the project - it is the implementation
step. The AI plans first (Article 1), works through the task list, and updates the Status
column in AI_PRJ_TASKS.md as each task changes state:
| 1 | Set up the project (package.json, tsconfig, vitest) | Done |
| 2 | Define the SQLite schema and migrations | In progress |> /next_ai
A one-line nudge ("Go next job") that tells the AI to pick up the next task without re-stating the context. Use it repeatedly to work down the list:
> /ai # task 1
> /next_ai # task 2
> /next_ai # task 3
> /close_ai
The work log is written to .aiprj/AI_LOG/ and the session exits. The filename is
YYYY-MM-DD_NNN.md, where NNN is a zero-padded counter starting at 000 that increments per
log - existing logs are never overwritten:
.aiprj/AI_LOG/
├── 2026-09-17_000.md # first session of the day
├── 2026-09-17_001.md # second session of the same day
└── 2026-09-18_000.md # counter restarts the next day
Each log embeds the full contents of instructions.md as it was at execution time (Article 7),
so a log stays readable even after the instructions have moved on.
Edit instructions.md, then reconcile the documents with /update_ai:
$EDITOR .aiprj/instructions.md # e.g. add "due date" to each TODO item> /update_ai
/update_ai re-reads instructions.md and rewrites all three documents to match, resolving any
inconsistency between them before it finishes. It may only write those three documents plus the
work log, so your source tree is untouched - run /ai afterwards to implement the change.
> /ai
Do not hand-edit AI_PRJ_*.md to change direction. Change instructions.md and re-run
/update_ai, so that the instructions remain the single source of truth.
cd ~/work/todo-api
claude> /update_ai # only if instructions.md changed since last time
> /ai # work the next task
> /next_ai # and the one after
> /next_ai
> /close_ai # writes 2026-09-17_000.md and exits
The same day with Codex CLI instead of Claude Code:
cd ~/work/todo-api
codex> $update-ai # only if instructions.md changed
> $ai # work the next task
> $next-ai # and the one after
> $next-ai
> $close-ai # writes 2026-09-17_000.md, then /exit yourself
The bundled .gitignore template ignores .aiprj along with AI_LOG/ and the three
AI_PRJ_*.md files, so requirements, design, tasks, and work logs stay local and uncommitted.
That is the right default for scratch work, but if you want the team to share the same contract,
remove the .aiprj line from .gitignore and commit the directory.
After setup, the AI manages the following documents:
| File | Content |
|---|---|
.aiprj/AI_PRJ_REQUIREMENTS.md |
Requirements document |
.aiprj/AI_PRJ_DESIGN.md |
Design specification document |
.aiprj/AI_PRJ_TASKS.md |
Implementation tasks and work instruction list |
.aiprj/AI_LOG/ |
Work logs (yyyy-MM-dd_NNN.md format, sequential, no overwriting) |
The AI operates according to the following guidelines:
- Must formulate a work plan before starting any task
- Distorting or reinterpreting the AI Operation Guidelines is prohibited
- Taking detours or modifying the approach beyond user instructions is prohibited
- Optimizing, rewriting, or reinterpreting user instructions is prohibited
- Must not stop until the user's instructions are fully completed
- Work logs must be saved to
.aiprj/AI_LOG/inyyyy-MM-dd_NNN.mdformat (sequential, no overwriting) - Work logs must include the contents of
.aiprj/instructions.md - Must not leave any trace of its involvement in generated or updated files
The NNN suffix of a work log is a zero-padded sequential number starting at 000.
A .claude/settings.json is installed alongside the commands, with an equivalent
.agent-cli/config.toml for agent-cli.
Denied: rm -rf ~/** and rm -rf //**, git remote add / git remote set-url (so the remote
cannot be swapped), npm publish / pnpm publish (so nothing is published by accident), and reads
of tmp/**, node_modules/, *.log, and .env* (secrets and noise).
Allowed: git, gh, node, pnpm, the touch / mkdir / cp / mv / rm / find /
grep / rg utilities, Read(**), Edit(**), and WebFetch. The edit mode defaults to
acceptEdits.
Other settings: the status line runs npx -y ccusage statusline --no-offline to display token
usage, and the environment sets BASH_DEFAULT_TIMEOUT_MS=300000, BASH_MAX_TIMEOUT_MS=1200000,
and DISABLE_AUTOUPDATER=0.
agent-cli (.agent-cli/config.toml): the same deny / allow lists expressed as agent-cli
permission rules (rule names are matched case-insensitively and ignoring _, so Claude Code's
Bash(git:*) form carries over unedited), plus write in the allow list. It is a project-local
overlay: agent-cli reads ~/.config/agent-cli/config.toml first and merges this file over it key
by key, so your provider, UI and history settings are untouched. It also sets
[runtime] commands_dir = ".agent-cli/commands" so the five slash commands are found, and
[tools.bash] timeout_ms = 300000 to match the Claude Code timeout. Confirm the resolved layers
with agent-cli config path.
aiprj/
├── install.sh # Setup script
├── .gitignore.aiprj # gitignore template
├── .aiprj/
│ ├── instructions.md.org # Instructions template
│ └── rules/
│ ├── setup_project.md # Setup rules
│ ├── exec_job.md # Task execution rules
│ ├── update_project.md # Update rules
│ └── close_ai.md # Exit rules
├── .claude/ # For Claude Code
│ ├── settings.json # Claude Code settings
│ └── commands/ # Slash command definitions
│ ├── setup_ai.md
│ ├── ai.md
│ ├── update_ai.md
│ ├── next_ai.md
│ └── close_ai.md
└── .agent-cli/ # For Claude Code compatible agent CLIs
├── config.toml # agent-cli settings (same rules as .claude/settings.json)
└── commands/ # Identical to .claude/commands/
└── .agents/ # For OpenAI Codex CLI
└── skills/ # Codex skills (SKILL.md + agents/openai.yaml each)
├── setup-ai/
├── ai/
├── update-ai/
├── next-ai/
└── close-ai/
curl(for setup)tar(for one-liner fallback), orgit- Claude Code CLI, OpenAI Codex CLI, or a Claude Code compatible agent CLI
- Node.js /
npx(optional - only for theccusagestatus line)