aistate 🧠

Your AI agents forget everything. aistate makes them remember.

😩 The Problem

You switch AI tools → context is gone.

• Cursor forgets after token limit
• Claude has no idea what you built
• ChatGPT starts from zero

You re-explain everything. Every time.

🚀 The Solution

aistate init
aistate add "build Stripe webhook"
aistate done T1
aistate log "using idempotency keys on Stripe"
aistate handoff

👉 Paste into any AI → continue instantly. No re-explaining.

🔥 See It In Action

$ aistate handoff

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
        🤖 AISTATE HANDOFF PROMPT
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

PROJECT: ecommerce-backend
LAST UPDATED: 2 hours ago

▶ CURRENT FOCUS: Stripe webhook endpoint

✅ COMPLETED:
  ✓ [T1] Spring Boot setup
  ✓ [T2] JWT auth (RS256)
  ✓ [T3] Product CRUD API

⏳ REMAINING:
  → [T4] Stripe webhook endpoint
     [T5] Order status updates
     [T6] Email notifications

📝 DECISIONS:
  [2026-04-29 14:32] RS256 JWT, secret in .env
  [2026-04-29 15:01] Stripe idempotency keys on all calls
  [2026-04-29 16:45] DO NOT refactor auth — it is complete

▶ NEXT TASK: "Stripe webhook endpoint"
  Continue from here. Do not redo completed tasks.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✓ Copied to clipboard. Paste into your AI agent.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📦 Install

🪟 Windows (PowerShell) — No Node Required

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

Add to PATH so you can run it from anywhere:

mkdir C:\aistate
Move-Item aistate.exe C:\aistate\
setx PATH "$env:PATH;C:\aistate"

Restart terminal, then:

aistate init

🐧 Linux — No Node Required

curl -L https://github.com/Abhir22/aistate/releases/latest/download/aistate-linux -o aistate
chmod +x aistate
sudo mv aistate /usr/local/bin/

🍎 macOS — No Node Required

curl -L https://github.com/Abhir22/aistate/releases/latest/download/aistate-macos -o aistate
chmod +x aistate
sudo mv aistate /usr/local/bin/

Via npm (if you have Node.js)

npm install -g aistate

🧰 Commands

| Command | Description | |---|---| | aistate init | Create .aistate/ in your project | | aistate add "task" | Add a task | | aistate done <id> | Mark task complete | | aistate log "note" | Save a decision or note | | aistate focus "text" | Set what you're working on now | | aistate status | Show all tasks + timestamps | | aistate handoff | Generate full context prompt + copy to clipboard |

🌍 Works Everywhere

• Any AI tool — Cursor, Claude, ChatGPT, Copilot, Windsurf, Trae ✅
• Any IDE ✅
• Any language — Java, Python, Node.js, Go, Rust, PHP ✅

No integration needed. aistate only touches the .aistate/ folder. Your code is never modified.

📂 What Gets Stored

your-project/
├── src/                 ← your code, untouched
└── .aistate/
    ├── state.json       ← tasks, IDs, timestamps, currentFocus
    ├── logs.md          ← your decisions and notes
    ├── context.md       ← optional project overview
    └── counter.json     ← internal ID tracking

Everything is plain text. Readable by humans and AI agents alike.

⚡ Real Workflow

# Monday — start feature in Cursor
aistate init
aistate add "build user authentication"
aistate add "add JWT middleware"
aistate add "write auth tests"
aistate focus "building user authentication"

# Cursor token limit hits — switch to Claude
aistate done T1
aistate log "using bcrypt with 12 salt rounds"
aistate handoff
# → paste prompt into Claude → continues instantly

# Wednesday — open Windsurf, same project
aistate handoff
# → paste → continue → no re-explaining

💾 Commit It or Ignore It

# Personal use only
echo ".aistate/" >> .gitignore

# Share context with your team
git add .aistate/
git commit -m "chore: add aistate project context"

🛣️ Roadmap

• [x] Task tracking (add, done, status)
• [x] Decision logging
• [x] Handoff prompt generation + clipboard copy
• [x] Relative timestamps (just now, 2h ago)
• [x] Binary distribution — Windows, Linux, macOS
• [ ] aistate undo — revert last done
• [ ] Project type auto-detection
• [ ] VS Code extension

🤝 Contributing

Issues and PRs are welcome.

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

See CONTRIBUTING.md for guidelines.

📄 License

MIT © Abhir Anand