Practical commands

# AICTX User Manual.

Fast answers for common tasks: install, inspect continuity, enable portability, use MCP, reduce output, query RepoMap, generate reports and clean up.

basic loop

    pip install aictx
    aictx install
    aictx init

    # then let your agent work normally

- `pip install aictx`: installs the AICTX Python package.
- `aictx install`: installs global runner integration files.
- `aictx init`: initializes AICTX in the current repository.
- Then let your agent run the resume/work/finalize lifecycle.

## Start here: install, initialize, let the agent work

### 1. Install and initialize

    pip install aictx
    aictx install
    aictx init

- `pip install aictx`: installs the AICTX Python package.
- `aictx install`: installs global runner integration files.
- `aictx init`: creates the repo-local AICTX setup.

### 2. Let your agent work

    aictx resume --repo . --task "continue current work" --json
    # work normally
    aictx finalize --repo . --status success --summary "what changed" --json

- `aictx resume`: gives the agent the continuity capsule before it starts.
- `# work normally`: the agent edits, tests and reasons as usual.
- `aictx finalize`: saves the outcome for the next session.

### 3. Inspect continuity

    aictx view --repo .
    aictx doctor --repo . --json

- `aictx view --repo .`: generates the local continuity report and map.
- `aictx doctor --repo . --json`: checks setup health in machine-readable form.

## Setup and health

### Install

    pip install aictx
    aictx install
    aictx init

- `pip install aictx`: installs the AICTX Python package.
- `aictx install`: installs global runner integration files.
- `aictx init`: initializes AICTX artifacts in the current repository.

### Check health

    aictx doctor --repo . --json
    aictx --version

- `aictx doctor --repo . --json`: validates repo-local setup, config and generated artifacts.
- `aictx --version`: prints the installed AICTX version.

### Manual resume/finalize

    aictx resume --repo . --task "continue current work" --json
    aictx finalize --repo . --status success --summary "what changed" --json

- `aictx resume`: returns the continuity capsule an agent should read before work.
- `aictx finalize`: records what happened so the next session can continue.

## Continuity and reports

### Continuity View

    aictx view --repo .

- `aictx view --repo .`: writes `.aictx/reports/continuity-view.md` and `.aictx/reports/continuity-map.mmd`.

### Real usage report

    aictx report real-usage

- `aictx report real-usage`: summarizes actual AICTX usage observed in the repository.

### Release-style diagnostics

    aictx doctor --repo . --release-readiness --json

- `aictx doctor --release-readiness`: runs stricter checks useful before publishing or release work.

## MCP and integrations

### Use MCP

    aictx mcp status --repo .
    aictx mcp-server --repo . --profile full

- `aictx mcp status --repo .`: shows whether MCP integration is configured for the repo.
- `aictx mcp-server --repo . --profile full`: starts the local MCP server over stdio.

### Disable MCP setup

    aictx install --no-mcp
    aictx init --no-mcp

- `aictx install --no-mcp`: installs global integration files without MCP configuration.
- `aictx init --no-mcp`: initializes a repo while skipping MCP setup.

### Profiles

    readonly  -> inspection only
    standard  -> lifecycle writes
    full      -> full AICTX continuity

- `readonly`: exposes inspection without lifecycle writes.
- `standard`: allows normal resume/finalize lifecycle writes.
- `full`: exposes the complete AICTX continuity surface.

## Portability

### Enable portable continuity

    aictx init --repo . --portable-continuity

- `aictx init --repo . --portable-continuity`: enables portable continuity files that can travel through Git; no cloud sync is used.

### Inspect portability

    aictx portability status --repo . --json

- `aictx portability status --repo . --json`: reports whether portable continuity is enabled and what is exposed.

### Disable portable continuity

    aictx init --no-portable-continuity

- `aictx init --no-portable-continuity`: disables portable continuity for the repository.

## Operational tools

### Work State

    aictx task start "Fix login token refresh"
    aictx task status --json
    aictx task update --json-patch '{"next_action":"run targeted auth tests"}' --json
    aictx task close --status resolved --json

- `aictx task start`: creates an active Work State for an unfinished task.
- `aictx task status --json`: prints the current Work State.
- `aictx task update --json-patch`: updates specific Work State fields.
- `aictx task close --status resolved --json`: closes the task when it is done.

### RepoMap

    aictx map status
    aictx map refresh
    aictx map query "startup banner"

- `aictx map status`: shows RepoMap availability and index state.
- `aictx map refresh`: refreshes the structural file/symbol map.
- `aictx map query`: searches RepoMap for relevant entry points.

### Messages

    aictx messages status
    aictx messages mute
    aictx messages unmute

- `aictx messages status`: shows whether AICTX runtime messages are visible.
- `aictx messages mute`: hides non-essential runtime messages.
- `aictx messages unmute`: restores runtime messages.

## Cleanup

### Clean repo-local setup

    aictx clean --repo .

- `aictx clean --repo .`: removes repo-local AICTX setup artifacts managed by AICTX.

### Uninstall global setup

    aictx uninstall

- `aictx uninstall`: removes global AICTX integration files from the machine.

## What this manual covers

This manual covers the practical user-facing surface: setup, health, continuity inspection, MCP, portability, Work State, RepoMap, reports, message controls and cleanup. For internals, use Technical Documentation.

Technical documentation