evactl — Evolvision AI Control

Local-first CLI that preserves AI context across sessions, tools, and teammates.

The Problem

Every time you start a new AI session, you lose everything — the decisions made, the progress so far, the half-finished feature context. Switching between Claude, Cursor, Windsurf, or any other tool means starting from scratch. evactl solves this by keeping a structured, tool-agnostic context layer right in your project.

Install

npm install -g evactl

Requires Node.js 18+.

Quick Start

# 1. Initialize an AI workspace in your project
cd my-project
evactl init

# 2. After an AI session, save your context
evactl save my-feature

# 3. Resume exactly where you left off
evactl resume my-feature

# 4. Switching tools? Generate a tool-agnostic handoff
evactl handoff my-feature

# 5. See all active sessions at a glance
evactl status

Commands

| Command | Description | |---|---| | evactl init | Initialize an AI workspace (ai/) in the current project | | evactl save <name> | Save current session context under a named session | | evactl resume [name] | Generate a resume prompt and copy it to clipboard | | evactl resume [name] --from-snapshot | Walk through session and snapshot history interactively | | evactl handoff [name] | Generate a tool-agnostic handoff prompt | | evactl snapshot [name] | Append a point-in-time snapshot of a session | | evactl snapshot list [name] | List all recorded snapshots with index and timestamp | | evactl status | Show workspace status — all sessions, last saved, active tasks | | evactl prompt | Generate a focused working prompt or create/manage templates | | evactl prompt list | List all saved prompt templates | | evactl prompt use <name> | Use a saved prompt template | | evactl agents run <agent> | Run an agent script from ai/agents/ | | evactl agents run-parallel <agent:session> ... | Run multiple agents in parallel | | evactl changelog | Generate CHANGELOG.md via summarizer → writer agent pipeline |

Agency Template

When running evactl init, you can choose the built-in agency template. It comes with two sub-templates tailored to how software agencies work:

• client — Structured for client projects: agency info, client contact, deliverables, sign-off tracking, and session files with Client Flags and acceptance criteria.

• internal — Structured for internal product builds: product context, team, architecture overview, roadmap, and session files with Related PRs / Branches tracking.

Each sub-template creates:

• ai/context.md — Project context prefilled for your use case
• ai/README.md — Workflow guide for your team
• Session files (task.md, progress.md, decisions.md, handoff.md) — created on first evactl save

Workspace Structure

ai/
├── context.md              # Global project context (shared across all sessions)
├── README.md               # Workflow guide (from template)
├── .evactl-template.json   # Records which template was used (auto-generated)
├── sessions/
│   └── <name>/
│       ├── task.md             # Current task and acceptance criteria
│       ├── progress.md         # Completed, in-progress, remaining
│       ├── decisions.md        # Decision log table
│       ├── handoff.md          # Notes for the next session
│       ├── session_snapshot.md # Auto-generated on evactl save
│       └── snapshot.md         # Append-only history of snapshots
├── prompts/                # Saved prompt templates
├── agents/                 # Agent scripts (.js or .sh)
└── memory/                 # Long-term memory files

Using with Claude Code (MCP Plugin)

MCP (Model Context Protocol) is a standard that lets AI tools call external services as structured tool calls. With evactl as an MCP server, Claude Code can save, resume, and check session status directly in the conversation — no terminal switching or copy/paste required.

Setup

Add this to your Claude Code MCP settings (~/.claude/claude_desktop_config.json or your IDE's MCP config):

{
  "mcpServers": {
    "evactl": {
      "command": "evactl",
      "args": ["mcp"]
    }
  }
}

Command line

claude mcp add --scope user evactl $(which evactl) mcp

Available MCP Tools

| Tool | Description | |---|---| | evactl_save | Save session context — pass session, accomplished, nextSteps, optionally blockers | | evactl_resume | Get the full resume prompt for a session — pass session name, optionally fromSnapshot (int) to resume from a historical snapshot | | evactl_handoff | Get a tool-agnostic handoff prompt — pass session name | | evactl_snapshot | Append a point-in-time snapshot — pass session name | | evactl_status | Get workspace status and all session summaries — no inputs required |

Usage Examples

Once configured, you can ask Claude naturally:

• "What sessions do I have?" → calls evactl_status
• "Resume the auth-refactor session" → calls evactl_resume
• "Save this session as payment-integration — we built the Stripe webhook handler, next is testing" → calls evactl_save
• "Take a snapshot of the onboarding-flow session" → calls evactl_snapshot

Parallel Agents (Phase 3)

Run multiple AI agents simultaneously, each working on a different named session. evactl coordinates their execution, labels their interleaved output, and optionally snapshots each session when they finish.

Usage

evactl agents run-parallel auth-agent:auth-refactor payment-agent:payment-integration

Each argument is an agent:session pair. auth-agent is the script name in ai/agents/, and auth-refactor is the session it operates on.

Agent Contract

Agents receive two CLI arguments injected by evactl:

node ai/agents/my-agent.js --session <name> --workspace <aiDir>

Agents can use these to read their session context or write results back:

// ai/agents/my-agent.js
const args = process.argv;
const session = args[args.indexOf('--session') + 1];
const workspace = args[args.indexOf('--workspace') + 1];
// read task.md, write progress updates, etc.

Shared Memory

Agents coordinate via ai/memory/ — a shared directory readable and writable by all agents. Always scope memory to your workflow session name so concurrent workflows don't overwrite each other.

Pass --scope <session> to your agents and write to the scoped path:

// write (scoped to workflow)
const scopedDir = `${workspace}/memory/${scope}`;
fs.mkdirSync(scopedDir, { recursive: true });
fs.writeFileSync(`${scopedDir}/status.md`, '## agent-1: done\n');

// read from another agent in the same workflow
const status = fs.readFileSync(`${scopedDir}/status.md`, 'utf-8');

Scoped memory lives at ai/memory/<scope>/<key>.md. Each workflow gets its own namespace — no cross-workflow collisions.

Single Agent with Session Context

Pass --session to a single agent run to inject context automatically:

evactl agents run my-agent --session auth-refactor

Snapshot History

Every time you run evactl snapshot, a full point-in-time capture of all session files is appended to ai/sessions/<name>/snapshot.md. This history is now fully queryable.

Browse snapshots

evactl snapshot list auth-feature
# Snapshots for "auth-feature" — 3 total
#
#   #1   Mar 15, 2026, 2:10 PM  [task.md, progress.md, decisions.md, handoff.md]
#   #2   Mar 16, 2026, 11:45 AM [task.md, progress.md, decisions.md, handoff.md]
#   #3   Mar 17, 2026, 5:22 PM  [task.md, progress.md, decisions.md, handoff.md]

Resume from any point in history

evactl resume --from-snapshot

No session name or snapshot number needed. The command walks you through two interactive steps:

1. Pick a session from the list of all saved sessions
2. Pick a snapshot by timestamp from that session's history

? Select a session:
  ❯ auth-feature   (last saved: Mar 17, 2026, 5:22 PM)
    payment-flow   (last saved: Mar 16, 2026, 11:30 AM)

? Select a snapshot to resume from (auth-feature):
  ❯ #1  Mar 15, 2026, 2:10 PM
    #2  Mar 16, 2026, 11:45 AM
    #3  Mar 17, 2026, 5:22 PM

The generated prompt is clearly marked as historical context so you know you're not looking at the current state.

If you know the index already (e.g. from a script or MCP), you can pass it directly: evactl resume auth-feature --from-snapshot 2. Via MCP, Claude uses evactl_resume with fromSnapshot: 2.

Changelog Pipeline

Generate CHANGELOG.md from your session progress files automatically using a 2-agent pipeline:

evactl changelog

This runs:

1. summarizer agent — reads all sessions' task.md and progress.md, writes structured summaries to scoped shared memory
2. writer agent — reads the summaries, extracts completed/in-progress/remaining items, generates CHANGELOG.md

Both agents are in ai/agents/ and can be customised. The pipeline uses scoped memory under ai/memory/changelog-generator/ so it never conflicts with other workflows.

Roadmap

• Phase 5: Cloud sync and team sharing of session context.

License

MIT © Evolvision