aistate

AIState is a CLI for tracking AI-assisted development context inside a repository.

It stores project state in a local .aistate/ directory so you can move between tools or sessions without rebuilding context from scratch.

---

What It Does

AIState currently supports:

• task tracking with init, add, done, and status
• note logging with log
• handoff generation with handoff
• project rules with rules add, rules list, and rules init
• template-based planning with plan

---

Install

From npm

npm install -g @abhir/aistate

From source

git clone https://github.com/Abhir22/aistate
cd aistate
npm install
npm run build
node ./bin/aistate.js --help

Standalone binaries

Release binaries are published for Windows, Linux, and macOS:

• aistate-win.exe
• aistate-linux
• aistate-macos

Example for Windows PowerShell:

Invoke-WebRequest -Uri "https://github.com/Abhir22/aistate/releases/latest/download/aistate-win.exe" -OutFile "aistate.exe"

---

Commands

Core commands

Command	Description
aistate init	Create .aistate/ in the current project
aistate add "task"	Add a new task
aistate done <id>	Mark a task as complete
aistate log "note"	Append a note to .aistate/logs.md
aistate status	Show current task status
aistate handoff	Generate a handoff summary and try to copy it to the clipboard
aistate plan "description"	Generate a task plan from a feature description

Rules commands

Command	Description
aistate rules add "rule"	Add a project rule
aistate rules list	List saved rules
aistate rules init	Run the interactive rules setup wizard

---

Current Workflow

1. Initialize AIState in a project

aistate init

This creates:

.aistate/
  state.json
  logs.md
  context.md
  counter.json
  rules.md

2. Add and complete tasks

aistate add "build auth middleware"
aistate add "write auth tests"
aistate done T1

3. Save notes

aistate log "using JWT access tokens with refresh rotation"

4. Add project rules

aistate rules add "Do not change database schema without approval"
aistate rules add "Run tests before handoff"
aistate rules list

Or use the wizard:

aistate rules init

5. Generate a feature plan

aistate plan "build jwt auth flow"

The command:

• detects a matching template such as auth, payment, api, database, or frontend
• previews the generated tasks
• asks for confirmation
• adds confirmed tasks to state.json

If no keyword matches, AIState uses a generic template.

6. Generate a handoff

aistate handoff

The handoff includes:

• completed tasks
• pending tasks
• recent notes
• project context
• saved rules
• next task guidance

---

Example Handoff Output

==========================================================
AIState Handoff
==========================================================

Project: my-project
Current Focus: none

Completed (1)
  [T1] Define auth requirements
    created 2026-05-01T10:00:00.000Z (2 hours ago)
    updated 2026-05-01T10:30:00.000Z (90 minutes ago)

Pending (2)
  [T2] Implement login endpoint
    created 2026-05-01T10:31:00.000Z (89 minutes ago)
    updated 2026-05-01T10:31:00.000Z (89 minutes ago)
  [T3] Write auth integration tests
    created 2026-05-01T10:32:00.000Z (88 minutes ago)
    updated 2026-05-01T10:32:00.000Z (88 minutes ago)

Rules (2)
  - Do not change database schema without approval
  - Run tests before handoff

Next Task
  Implement login endpoint
  Continue from here without redoing completed work.

==========================================================

---

Notes

• AIState only writes inside .aistate/.
• It does not modify your application source code.
• The focus command shown in older docs is not currently implemented.

---

Development

npm install
npm run build
node ./bin/aistate.js --help

Useful command checks:

node ./bin/aistate.js rules --help
node ./bin/aistate.js plan --help

---

License

MIT