Metadata-Version: 2.4
Name: aictx
Version: 4.1.0
Summary: Repo-local continuity runtime for coding agents
Author: Santi Santamaria
License-Expression: MIT
Project-URL: Homepage, https://github.com/oldskultxo/aictx
Project-URL: Repository, https://github.com/oldskultxo/aictx
Project-URL: Issues, https://github.com/oldskultxo/aictx/issues
Keywords: ai,llm,coding-agents,continuity,agent-memory,repo-local,developer-tools,execution-memory,codex,claude
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Development Status :: 4 - Beta
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# aictx

AICTX is a repo-local continuity runtime for coding agents.

It helps each new session behave like the same repo-native engineer continuing prior work.

Current documented implementation: `4.1.0`

---

## Why this exists

Most agent workflows start from scratch every time.

aictx allows them to reuse what already worked.

---

## What aictx is

A repo-local continuity runtime for coding agents.

It records real execution, preserves continuity artifacts inside the repository, and reuses successful strategies in later executions.

- repo-local continuity runtime
- real execution logging
- reusable strategy memory
- canonical handoff, decisions, semantic repo, staleness, and continuity metrics artifacts
- structured execution signal capture with provenance
- failure and repo-area memory
- lightweight runtime guidance and post-task summaries for coding agents

---

## Safety model

AICTX modifies repository files and can optionally install runner integrations.
By default it creates repo-local runtime artifacts only during repo setup, and `aictx install` does not modify global Codex files.
Global Codex integration requires `aictx install --install-codex-global`.

---

## Quick start

```bash
pip install aictx
aictx install
cd your-repo
aictx init
```

After `aictx init`, you can use your coding agent normally in that repo.

Manual `aictx` commands after initialization are optional:
- the intended flow is `install` + `init`, then agent-driven usage
- `suggest`, `reflect`, `reuse`, and `report real-usage` remain available for inspection, debugging, or manual control
- Claude/Codex integration files and hooks added by `init` are there to help the agent use `aictx` automatically when the runner respects repo instructions

---

## Public CLI

```bash
aictx install
aictx init
aictx suggest
aictx reflect
aictx reuse
aictx report real-usage
aictx clean
aictx uninstall
```

Only `install` and `init` are part of the normal setup path.

The rest of the public commands are optional operational commands:
- `suggest`, `reflect`, `reuse` -> for manual inspection or explicit agent calls
- `report real-usage` -> for reviewing stored execution data
- `clean`, `uninstall` -> for removing AICTX-managed content

---

## What aictx does

* records real execution in `.aictx/metrics/execution_logs.jsonl`
* writes operational feedback in `.aictx/metrics/execution_feedback.jsonl`
* stores successful and failed strategies in `.aictx/strategy_memory/strategies.jsonl`
* stores continuity artifacts in `.aictx/continuity/`
  * `handoff.json`
  * `handoffs.jsonl` (rolling recent handoff history)
  * `decisions.jsonl`
  * `semantic_repo.json`
  * `dedupe_report.json`
  * `staleness.json`
  * `continuity_metrics.json`
  * `last_execution_summary.md` (latest detailed finalize summary)
* captures available files, commands, tests, and errors with provenance instead of inventing data
* stores repo-local failure patterns and area memory for later debugging/context
* reuses only successful strategies during later executions
* returns `agent_summary` and `agent_summary_text` after finalize; agents must append `agent_summary_text` to final user responses for non-trivial tasks
* exposes small JSON commands for runtime guidance
* does not rely on hidden model memory or opaque cross-repo state

---

## What AICTX modifies

Repo-local:
- `.aictx/`
- AICTX-managed blocks in `AGENTS.md` and `CLAUDE.md`
- `.claude/settings.json` merged AICTX hook entries
- `.claude/hooks/aictx_*.py`
- `.gitignore` entries for AICTX runtime paths

Optional global:
- `~/.codex/AGENTS.override.md`
- `~/.codex/AICTX_Codex.md`
- `~/.codex/config.toml`

Global Codex files are only updated when `--install-codex-global` is passed.

---

## Idempotency guarantees

- `aictx init` is non-destructive for existing AICTX execution logs and strategy memory
- existing `.aictx/metrics/*.jsonl` and `.aictx/strategy_memory/*.jsonl` files are preserved
- `.claude/settings.json` is merged, not overwritten
- AICTX-managed Markdown blocks and hooks are idempotent
- `aictx init` does not delete legacy non-AICTX paths

---

## What aictx does NOT do

aictx does not optimize your agent.
aictx does not guarantee better performance.

It makes past executions observable and reusable.

---

## Who this is for

- engineers using coding agents repeatedly in the same repository
- teams that want repo-local execution history and reusable strategies
- users who prefer traceable artifacts over heuristic-heavy automation

## Who this is not for

- users expecting guaranteed productivity gains
- teams looking for a full orchestration platform
- workflows that do not preserve repo-level instructions or execution discipline

---

## Runtime loop

1. `prepare_execution()` loads prior successful strategies and may attach `execution_hint`
2. for non-trivial work it may also build a bounded packet/context payload and continuity summary
3. the agent executes
4. `finalize_execution()` records logs, feedback, strategy memory, and `agent_summary_text`
5. the agent appends `agent_summary_text` to the final user response; if unavailable, it says `AICTX summary unavailable`
6. the next execution can reuse successful strategies and ignore failed ones

---

## Artifact contract

The stable repo-local continuity artifact contract in `4.1.0` is:

```text
.aictx/continuity/session.json
.aictx/continuity/handoff.json
.aictx/continuity/decisions.jsonl
.aictx/continuity/semantic_repo.json
.aictx/continuity/dedupe_report.json
.aictx/continuity/staleness.json
.aictx/continuity/continuity_metrics.json
.aictx/strategy_memory/strategies.jsonl
.aictx/failure_memory/failure_patterns.jsonl
.aictx/metrics/execution_logs.jsonl
.aictx/metrics/execution_feedback.jsonl
```

Behavior expectations:

- continuity artifacts are repo-local and inspectable
- startup loads only bounded, deterministic continuity context
- startup banner behavior is visible-session aware and shown at most once per visible session
- packet/context middleware may be built for non-trivial work and remains inspectable when present
- failed strategies remain in history but are excluded from positive reuse
- maintenance and staleness files mark or summarize; they do not imply hidden ML or automatic repair

Additional runtime continuity outputs may appear (not part of the stable contract set above), including:
- `.aictx/continuity/handoffs.jsonl`
- `.aictx/continuity/last_execution_summary.md`

## Main runtime artifacts

```text
.aictx/
  continuity/
    handoff.json
    handoffs.jsonl
    decisions.jsonl
    semantic_repo.json
    dedupe_report.json
    staleness.json
    continuity_metrics.json
    last_execution_summary.md
  metrics/
    execution_logs.jsonl
    execution_feedback.jsonl
  strategy_memory/
    strategies.jsonl
```

---

## Additional properties

* repo-local artifacts are the source of truth; execution history and strategy memory stay inspectable inside the repository
* failed strategies are stored, but they are excluded from reuse by default
* public operational command outputs are deterministic and machine-readable JSON; internal `run-execution` without `--json` also prints the user-facing AICTX summary
* AICTX-managed changes can be removed cleanly with `aictx clean` and `aictx uninstall`

---

## Notes

* file tracking depends on explicit input from the agent/runtime; wrapped execution can capture commands, tests, errors, and edited files best-effort
* strategy reuse is heuristic: matching task type, prompt similarity, overlapping files, primary entry point, commands/tests/errors, and area are preferred, with recency as a secondary signal
* continuity loading is layered: session identity, handoff, recent decisions, failure patterns, semantic repo memory, procedural reuse, maintenance hygiene, staleness filtering, and aggregate continuity metrics
* task typing uses explicit metadata first, then deterministic keyword/path inference, then `unknown`
* capture provenance distinguishes explicit, runtime-observed, heuristic, and unknown signals
* middleware packet generation is conservative and task-dependent, not unconditional for every execution
* `reflect` is intentionally small-scope: it only looks at the latest execution log, but it can now return issue classification, counts, suggested next action, and recommended entry points
* `suggest` and `reuse` can rank with extra context such as request text, files, commands, tests, and notable errors when that context is provided
* failed strategies are stored and excluded from positive reuse hints; they may still inform failure-aware avoidance and debugging context
* no synthetic benchmarks or estimated improvements are reported

---

## Cleanup

* `aictx clean` removes only AICTX-managed content from the current repository: the `.aictx/` scaffold, AICTX blocks in `AGENTS.md` / `CLAUDE.md`, legacy AICTX content in `AGENTS.override.md` when present, AICTX Claude hooks/settings, and the `.gitignore` entry added by AICTX
* `aictx uninstall` removes AICTX-managed content from all registered repositories and removes global AICTX state under `~/.aictx`, plus AICTX-managed Codex global instructions/config lines
* both commands are conservative: they only remove content that AICTX created or marked as AICTX-managed

---

## Possible evolution

The current `4.1.0` runtime keeps continuity deterministic and inspectable rather than turning into an opaque agent platform.

Possible future work, based on real usage:

* better file access capture from agent/runtime integrations
* broader runner-native signal capture where supported
* clearer comparison across repeated task categories
* stronger runner-native automation where supported
* richer repo-level reporting built only from real execution history
* additional visible-session integration support across runners

Not part of the current product contract:

* hidden cross-session model state
* autonomous repo repair
* guaranteed optimization claims

---

## Read next

* [Usage](docs/USAGE.md)
* [Demo](docs/DEMO.md)
* [Limitations](docs/LIMITATIONS.md)
* [Safety](docs/SAFETY.md)
* [Upgrade](docs/UPGRADE.md)
* [Execution summary](docs/EXECUTION_SUMMARY.md)
* [Failure memory](docs/FAILURE_MEMORY.md)
* [Area memory](docs/AREA_MEMORY.md)
