AICTX

Local-first AI coding session recorder and handoff CLI.

AICTX helps developers preserve AI-assisted development context, track visible workflow, capture command/test output, and generate compact handoffs for the next AI agent when a session ends, context is lost, or a usage limit is reached.

Install the npm package:

npm install -g aicontext-cli

Use the CLI command:

aictx --help

Why AICTX?

AI coding sessions often lose context.

You may hit a session limit, switch AI tools, restart a conversation, or need to hand work to another agent. AICTX keeps a local memory trail of what happened during development so the next AI can continue with less guessing.

AICTX can track:

AI-visible plans
AI-generated summaries
AI decisions
AI TODOs
AI next steps
changed files
commands run
errors
test output
checkpoints
handoffs

AICTX does not capture hidden AI chain-of-thought. It captures visible workflow artifacts only.

Features

• Local-first project memory in .aictx/
• SQLite-backed state
• Timeline event log
• AI handoff generation
• Compact context packs
• Transcript import/watch for visible AI chats
• Command/test output capture with aictx run -- <command>
• Workflow capture modes: transcript, shell, optional MCP
• AST symbol indexing for TypeScript projects
• Local semantic search support
• Optional Obsidian mirror
• Optional MCP server for AI tool access
• Secret redaction before storage/output

Install

Global install

npm install -g aicontext-cli

Then run:

aictx --help

The npm package name is:

aicontext-cli

The installed terminal command is:

aictx

Requirements

Node.js >= 18
npm, pnpm, yarn, or bun

Recommended:

Node.js 20+
pnpm 9+

Quick Start

Go to a project you want to track:

cd your-project

Initialize AICTX:

aictx init

Start a development session:

aictx start "Build semantic search provider system"

Check status:

aictx status

Generate a handoff:

aictx handoff --compact

Daily Workflow

Recommended setup during AI-assisted development:

cd your-project

aictx init
aictx start "Implement workflow capture"

In one terminal, watch project changes:

aictx watch

In another terminal, run tests/builds through AICTX:

aictx run -- pnpm test
aictx run -- pnpm build

When the AI session is about to end, generate handoff:

aictx handoff --compact

Give the generated handoff to the next AI agent.

Command Capture

Use aictx run -- instead of running commands directly when you want output captured.

aictx run -- pnpm test
aictx run -- pnpm build
aictx run -- npm run lint
aictx run -- npx vitest --run
aictx run -- npx playwright test

The -- matters.

Everything after -- belongs to the command being captured.

Example:

aictx run -- vitest --run

AICTX captures:

command
arguments
working directory
stdout summary
stderr summary
exit code
test status
errors
timeline event

Transcript Workflow Capture

AICTX can import or watch visible AI chat transcripts.

Import a transcript:

aictx transcript import ./chat.md

Watch the default transcript file:

aictx transcript watch

Default transcript path:

.aictx/inbox/current-transcript.md

Watch a custom transcript file:

aictx transcript watch ./current-ai-session.md

Extract from the configured default transcript path:

aictx transcript extract

Transcript extraction can detect:

plans
summaries
decisions
TODOs
next steps
errors
mentioned files
mentioned commands

Workflow Capture Modes

AICTX supports three workflow capture modes.

transcript
shell
mcp

Default mode:

transcript

Check workflow status:

aictx workflow status

Set transcript mode:

aictx workflow mode transcript

Set shell mode:

aictx workflow mode shell

Set MCP mode only after enabling MCP workflow writes:

aictx workflow mode mcp

Start the configured workflow mode:

aictx workflow start

Transcript mode

Best for capturing visible AI workflow.

AI-visible plan
AI-generated summary
AI decisions
AI TODOs
AI next steps
errors discussed in chat
files mentioned by AI
commands suggested by AI

Shell mode

Best for capturing technical evidence.

commands run
exit codes
test output
build output
stderr
compiler errors
lint errors

Use:

aictx run -- pnpm test

MCP mode

Optional advanced mode.

Compatible AI tools can write structured workflow events directly into AICTX memory through MCP.

MCP is disabled by default.

Handoff Generation

Generate a compact handoff:

aictx handoff --compact

Generate a fuller handoff:

aictx handoff

AICTX handoff can include:

session goal
current state
recent timeline
decisions
TODOs
next steps
changed files
commands run
test output
errors/blockers
symbol index summary
search hints

The handoff is designed to be pasted into a fresh AI session.

Search

Keyword search:

aictx search "auth refresh"

Semantic search:

aictx search "login fails after session expires" --semantic

Hybrid search:

aictx search "auth refresh bug" --hybrid

Direct key lookup:

aictx get decision.transformers-default

AST Symbol Index

Build a TypeScript symbol index:

aictx symbols

AICTX can index:

functions
classes
interfaces
types
exports

This helps AI tools find important code symbols quickly.

Embeddings

Create local semantic search embeddings:

aictx embed

Use a specific provider:

aictx embed --provider transformers

Optional Ollama provider:

aictx embed --provider ollama

Check embedding status:

aictx embeddings status

AICTX should not require cloud APIs for embeddings.

Checkpoints

Save a checkpoint:

aictx checkpoint --title "Transcript parser implemented"

Save a checkpoint with next step:

aictx checkpoint --title "Workflow capture scaffolded" --next "Add tests and run pnpm check"

Notes

Manual notes are optional, but useful when you want to force a specific memory item.

aictx note "Use Transformers.js as default embedding provider" --type decision
aictx note "Fix stale vector detection next" --type next-step
aictx note "Vitest failed because vectors were not normalized" --type error

Obsidian Mirror

Obsidian support is optional.

SQLite, timeline, and indexes remain the source of truth.

Initialize Obsidian mirror:

aictx obsidian init

Sync memory to Obsidian:

aictx obsidian sync

Use Obsidian when you want human-readable project memory.

Optional MCP Server

Start MCP server:

aictx mcp start

Show MCP help:

aictx mcp --help

MCP is an optional access layer. It does not replace the CLI.

Privacy

AICTX is local-first.

Memory is stored in your project under .aictx/
No cloud API is required by default
No hidden AI thought process is captured
Visible transcripts can be imported/watched
Command output can be captured when you choose to use aictx run
Secrets are redacted before storage/output

Do not commit .aictx/ unless you intentionally want to share project memory.

Recommended .gitignore entry:

.aictx/

Files Created

Typical AICTX project memory:

.aictx/
  state.sqlite
  timeline.jsonl
  current-session.json
  config.json
  indexes/
  snapshots/
  checkpoints/
  handoffs/
  embeddings/
  inbox/

Common Commands

aictx --help
aictx --version

aictx init
aictx status
aictx doctor

aictx start "Build feature"
aictx watch
aictx timeline

aictx note "Use SQLite as source of truth" --type decision
aictx checkpoint --title "Parser working"

aictx run -- pnpm test
aictx run -- pnpm build

aictx transcript import ./chat.md
aictx transcript watch
aictx transcript extract

aictx workflow status
aictx workflow mode transcript
aictx workflow mode shell

aictx symbols
aictx embed
aictx embeddings status

aictx search "auth refresh"
aictx search "login session bug" --semantic
aictx get decision.sqlite-source-of-truth

aictx handoff --compact
aictx pack

aictx obsidian init
aictx obsidian sync

aictx mcp start

Development

Clone the repo:

git clone <repo-url>
cd aictx

Install dependencies:

pnpm install

Run in development:

pnpm dev -- --help

Run a command through dev mode:

pnpm dev -- run -- echo hello

Build:

pnpm build

Run tests:

pnpm test

Run full check:

pnpm check

Local Publish Smoke Test

Before publishing to npm:

pnpm check
pnpm build
npm pack

Install packed tarball globally:

npm install -g ./aicontext-cli-*.tgz

Test:

aictx --help
aictx --version

Publishing

Dry run:

npm publish --dry-run

Publish:

npm publish

After publish, install from npm:

npm install -g aicontext-cli

Then verify:

aictx --help
aictx --version

Troubleshooting

zsh: command not found: aictx

Install globally:

npm install -g aicontext-cli

Or test locally:

npm link

Check npm global prefix:

npm prefix -g

Permission denied

Make sure built CLI has a shebang:

head -n 1 dist/index.js

Expected:

#!/usr/bin/env node

Make executable:

chmod +x dist/index.js

aictx run does not pass flags

Use --:

aictx run -- vitest --run

Not:

aictx run vitest --run

Version already exists on npm

Bump version:

npm version patch
npm publish

Package Name vs Command Name

The npm package is installed as:

npm install -g aicontext-cli

But the command is still:

aictx

This works because package.json should include:

{
  "name": "aicontext-cli",
  "bin": {
    "aictx": "dist/index.js"
  }
}

What AICTX Does Not Do

AICTX does not:

capture hidden AI chain-of-thought
replace Git
replace your test suite
require Obsidian
require MCP
require cloud APIs
guarantee perfect semantic search
automatically know terminal commands unless run through aictx run or supported shell capture

Recommended First Commands

aictx init
aictx start "My current development task"
aictx transcript watch

In another terminal:

aictx watch

Run tests through AICTX:

aictx run -- pnpm test

Generate handoff:

aictx handoff --compact

License

MIT License

Copyright (c) 2026 Dharsan Guruparan

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.