Installation
This guide explains the setup flow and what AICTX asks during installation and repo initialization.
The normal product experience is:
install -> init -> use your coding agent normally
Manual AICTX commands are mainly for inspection, debugging, demos, and advanced integrations.
Requirements
- Python 3.11+
pip- a repository on disk
- git is recommended
- optional: Tree-sitter support through
aictx[repomap] - optional: Codex and/or Claude if you want runner integrations
Fast path
From inside the target repository:
pip install aictx
aictx install
aictx init
aictx --version
Use aictx --version to verify the installed CLI version.
Equivalent explicit repo form:
aictx init --repo .
Use --repo <path> when running from outside the repository.
Non-interactive setup
For CI, demos, tests, or scripted installation:
aictx install --yes
aictx init --repo . --yes
Demo/temporary repo without registering:
aictx init --repo . --yes --no-register
Optional global Codex files:
aictx install --yes --install-codex-global
Optional RepoMap request:
pip install "aictx[repomap]"
aictx install --yes --with-repomap
aictx init --repo . --yes
Interactive behavior
The CLI uses three interactive helpers:
ask_yes_no(prompt, default)
ask_text(prompt, default)
ask_choice(prompt, options, default)
That means setup questions behave consistently:
- yes/no prompts accept
y,yes,n, or empty input for the default; - text prompts show a default in brackets when one exists;
- choice prompts list numbered options and ask
Select option number:; - invalid choices are rejected and asked again.
Prompt wording may change between releases. The decisions documented below are the current setup decisions users should expect.
aictx install: global/runtime setup
aictx install prepares AICTX global/runtime state.
It is about the AICTX installation and workspace-level setup. It should not be described as the place where repo communication mode is chosen.
Current install decisions:
| Setup decision | Example answer | Effect |
|---|---|---|
| Workspace id | default |
Stores active workspace identity |
| Workspace root | /Users/me/dev or empty |
Defines workspace root when provided |
| Cross-project mode | --cross-project-mode workspace |
Controls workspace-level cross-project behavior; accepted values are workspace, explicit, and disabled |
| Global Codex install | --install-codex-global |
Allows AICTX-managed global Codex files |
| RepoMap request | --with-repomap |
Marks RepoMap as requested in global config |
| Dry run | --dry-run |
Shows intended changes without applying them |
| Non-interactive mode | --yes |
Uses defaults and skips confirmation prompts |
Representative interactive flow:
aictx install
Default workspace name [default]: default
Add a workspace root now? [Y/n]: y
Workspace root [/Users/me/projects]: /Users/me/dev
Enable RepoMap support using Tree-sitter? [y/N]: n
Recommended simple answer pattern:
Press Enter for defaults unless you specifically want global Codex integration, RepoMap, or custom workspace behavior.
aictx init: repo-local setup
aictx init prepares one repository.
This is where repo-local runtime behavior is configured, including communication mode.
Current init decisions:
| Setup decision | Example answer | Effect |
|---|---|---|
| Repo path | current directory or --repo <path> |
Selects target repository |
Write .gitignore entries |
default yes unless --no-gitignore |
Keeps local runtime artifacts ignored or applies the portable-continuity policy |
| Register repo | default yes unless --no-register |
Adds repo to AICTX registry for cleanup/uninstall |
| Git-portable continuity | default N for new repos |
Switches the AICTX-managed .gitignore policy and writes .aictx/continuity/portability.json |
| Communication mode | default disabled; optional caveman_full |
Stores repo preference under .aictx/memory/user_preferences.json |
| Initialize scaffold | Y |
Creates/updates .aictx/, AGENTS.md, CLAUDE.md, .claude/*, and runtime scaffolding |
| RepoMap initialization | default when globally requested | Writes/refreshes .aictx/repo_map/* if available |
Representative interactive flow:
aictx init
This will initialize AICTX in the current repository.
Write .gitignore entries if missing? [Y/n]: y
Register this repo in the active workspace? [Y/n]: y
Enable AICTX git-portable continuity? [y/N]: n
Select communication mode:
1. disabled (default)
2. caveman_lite
3. caveman_full
4. caveman_ultra
Select option number: 1
Initialize full starter scaffold now? [Y/n]: y
Simple one-shot setup:
aictx init --repo . --yes
Portable continuity remains disabled by default for new repos. To opt in:
aictx init --repo . --portable-continuity
aictx init --repo . --yes --portable-continuity
aictx init --repo . --no-portable-continuity
Demo/test setup without registry updates:
aictx init --repo . --yes --no-register
Communication mode
Communication mode is repo-local.
It belongs to aictx init, because it is persisted in repo user preferences and then loaded into the repo runtime state.
Available modes:
| Mode | Intended use |
|---|---|
disabled |
No special communication layer; default |
caveman_lite |
Slightly compressed communication |
caveman_full |
Strong compact communication mode |
caveman_ultra |
Very aggressive compression |
If unsure, use the default. Choose caveman_full only if you want AICTX to ask supported agents for compact runtime communication.
What files may appear after init
Common repo-local files:
.aictx/
AGENTS.md
CLAUDE.md
.claude/settings.json
.claude/hooks/aictx_session_start.py
.claude/hooks/aictx_user_prompt_submit.py
.claude/hooks/aictx_pre_tool_use.py
RepoMap files when enabled:
.aictx/repo_map/config.json
.aictx/repo_map/manifest.json
.aictx/repo_map/index.json
.aictx/repo_map/status.json
Codex setup
Minimal:
pip install aictx
aictx install
aictx init
Optional global Codex support:
aictx install --install-codex-global
Repo-level Codex guidance is written through AGENTS.md.
Claude setup
pip install aictx
aictx install
aictx init
AICTX can create/update:
CLAUDE.md
.claude/settings.json
.claude/hooks/aictx_session_start.py
.claude/hooks/aictx_user_prompt_submit.py
.claude/hooks/aictx_pre_tool_use.py
RepoMap setup
pip install "aictx[repomap]"
aictx install --with-repomap
aictx init
aictx map status
Refresh manually:
aictx map refresh
Query:
aictx map query "startup banner"
Generic agent setup
Any agent can use AICTX through the CLI/runtime contract:
aictx resume --repo . --task "<task goal>" --json
aictx finalize --repo . --status success|failure --summary "<what happened>" --json
The agent must cooperate with the runtime contract for best results.
Advanced integrations may also use aictx internal execution prepare ...,
aictx internal execution finalize ..., or aictx internal run-execution ...
when wrapping execution directly.
After setup
Use your coding agent normally.
AICTX is unmuted by default after init. Use aictx messages mute if you want to suppress automatic startup and summary messages.
Manual inspection commands:
aictx next
aictx task status --json
aictx map status
aictx report real-usage
Cleanup
See Cleanup.
Quick commands:
aictx clean --repo .
aictx uninstall