Agentic Planning

Persistent intention infrastructure for AI agents.

Goals with physics. Decisions with memory. Commitments with trust. One file holds your agent's entire strategic brain.

Architecture · Quickstart · Problems Solved · How It Works · Why · MCP Tools · Benchmarks · Install · API · Papers

---

Every AI agent forgets what it wanted.

Claude starts a coding session with five goals — by the end, three are abandoned and nobody remembers why. GPT commits to a deadline, then the next session treats it as a suggestion. Your copilot decomposes a task into subtasks, and by session three the subtask tree is gone. Every plan starts from zero.

The current fixes don't work. Todo lists lose hierarchy — you get flat items, never "which goal does this serve?". Session notes are ephemeral and break across restarts. Kanban boards are external and disconnected from the agent's reasoning. Provider memory captures facts but never intentions.

AgenticPlanning stores your agent's strategic state as a living intention graph in a single binary file. Not "write down your goals." Your agent has a strategic brain — goals with physics, decisions with preserved shadow paths, commitments with trust accounting, and progress with momentum — all connected, all queryable in microseconds.

Problems Solved (Read This First)

• Problem: goal drift — agents lose track of objectives across sessions.

Solved: persistent .aplan files preserve the full goal hierarchy with status, priority, blockers, and relationships that survive restarts, model switches, and long gaps.

• Problem: decision amnesia — shadow paths and rejected alternatives vanish.

Solved: decision crystallization preserves every option considered, the reasoning chain, and the roads not taken.

• Problem: commitment overload — agents take on too many promises with no accountability.

Solved: weighted commitment tracking with stakeholder entanglement, deadline physics, and at-risk forecasting.

• Problem: progress blindness — no momentum, no velocity, no forecasts.

Solved: progress physics engine computes momentum, gravity wells, blocker echoes, and completion forecasts.

• Problem: strategic isolation — goals exist in a vacuum, disconnected from decisions and commitments.

Solved: intention singularity collapses the full strategic state into a unified view with tension detection and theme extraction.

from agentic_planning import PlanningGraph

planner = PlanningGraph("strategy.aplan")

# Your agent plans
planner.create_goal("Ship v2.0", intention="Complete rewrite with new architecture")

# View all goals
goals = planner.list_goals()

CLI for operational workflows:

aplan goal create "Ship v2.0" --intention "Complete rewrite with new architecture"
aplan decision create --goal g-001 --question "Which runtime?" --option "Tokio" --option "async-std"
aplan commitment create --goal g-001 --promise "Demo by Friday" --stakeholder "team-lead"
aplan singularity --file strategy.aplan

One file holds everything. Works with Claude, GPT, Ollama, or any LLM you switch to next.

---

Architecture

> v0.1.0 — Persistent intention infrastructure.

AgenticPlanning is a Rust-native planning engine that treats strategic state as first-class data. Goals are living entities with physics. Decisions crystallize from option spaces, preserving shadow paths. Commitments carry weight and trust. Progress has momentum.

Core Capabilities

• Goal Engine — Goals with hierarchy, physics, lifecycle, dream simulation, reincarnation, and decomposition.
• Decision Engine — Crystallization with shadow path preservation, archaeology, prophecy, regret analysis, and counterfactual projection.
• Commitment Tracker — Weighted promises with stakeholder entanglement, deadline physics, renegotiation, and at-risk forecasting.
• Query Engine — Singularity collapse, intention position, path analysis, tension detection, theme extraction, and center-of-gravity.
• Progress Physics — Momentum, gravity wells, blocker echoes, velocity tracking, trend analysis, and completion forecasts.
• Dream Surfaces — Goal dreaming, collective dreaming, interpretation, insight extraction, and accuracy tracking.
• Federation — Cross-agent goal sharing, sync, handoff, and status propagation.
• Consensus — Multi-stakeholder decision workflows with rounds, voting, synthesis, and crystallization.

Architecture Overview

+-------------------------------------------------------------+
|                     YOUR AI AGENT                           |
|           (Claude, Cursor, Windsurf, Cody)                  |
+----------------------------+--------------------------------+
                             |
                  +----------v----------+
                  |      MCP LAYER      |
                  |   13 Tools + 9 Res  |
                  +----------+----------+
                             |
+----------------------------v--------------------------------+
|                    PLANNING ENGINE                           |
+-----------+-----------+------------+----------+-------------+
| Goal      | Decision  | Commitment | Progress | Query       |
| Engine    | Engine    | Tracker    | Physics  | Engine      |
+-----------+-----------+------------+----------+-------------+
                             |
                  +----------v----------+
                  |     .aplan FILE     |
                  |  (your intentions)  |
                  +---------------------+

---

MCP Tools

AgenticPlanning exposes 13 MCP tools for AI agents:

Planning Tools

| Tool | Description | Operations | |:---|:---|:---| | planning_goal | Living goal management with full lifecycle support | create, list, show, activate, progress, complete, abandon, pause, resume, block, unblock, decompose, link, tree, feelings, physics, dream, reincarnate | | planning_decision | Decision crystallization with shadow path preservation | create, option, crystallize, show, shadows, chain, archaeology, prophecy, counterfactual, regret, recrystallize | | planning_commitment | Weighted commitment management | create, list, show, fulfill, break, renegotiate, entangle, inventory, duesoon, atrisk | | planning_progress | Progress physics | momentum, gravity, blockers, echoes, forecast, velocity, trend | | planning_singularity | Intention singularity | collapse, position, path, tensions, themes, center, vision | | planning_dream | Dream surfaces | goal, collective, interpret, insights, accuracy, history | | planning_counterfactual | Counterfactual projection | project, compare, learn, timeline | | planning_chain | Decision chain analysis | trace, cascade, roots, leaves, visualize | | planning_consensus | Consensus workflows | start, round, synthesize, vote, status, crystallize | | planning_federate | Goal federation | create, join, sync, handoff, status, members | | planning_metamorphosis | Goal metamorphosis | detect, approve, history, predict, stage | | planning_workspace | Workspace management | create, switch, list, compare, merge, delete | | planning_context_log | Log the intent and context behind a planning action | (direct params: intent, finding, topic) |

MCP Resources

planning://goals             -- All goals
planning://goals/{id}        -- Goal by ID
planning://decisions         -- All decisions
planning://commitments       -- All commitments
planning://singularity       -- Current intention singularity
planning://status            -- Planning status overview
planning://dreams/{id}       -- Dream detail by ID
planning://consensus/{id}    -- Consensus session state
planning://workspace/{id}    -- Workspace summary

MCP Prompts

| Prompt | Description | |:---|:---| | planning_review | Generate planning review (daily/weekly/monthly) | | goal_decomposition | Decompose a goal into sub-goals | | decision_analysis | Analyze a pending decision | | commitment_check | Check commitment health |

---

Benchmarks

Rust core. Atomic file I/O. Zero external dependencies. Real numbers from Criterion statistical benchmarks:

| Operation | Time | Scale | |:---|---:|:---| | Create goal | 340 ns | 1K graph | | Create decision | 480 ns | 1K graph | | Goal hierarchy | 2.5 ms | 1K graph | | Singularity view | 7.1 ms | 1K graph | | Decision tree | 1.3 ms | 1K graph | | Dream simulation | 9.5 ms | 1K graph | | Write 1K goals to file | 28.4 ms | -- | | Read 1K goals from file | 3.1 ms | -- |

> All benchmarks measured with Criterion (100 samples) on Apple M4 Pro, 64 GB, Rust 1.90.0 --release.

Capacity: A year of intensive planning produces a ~6 MB file. A decade fits in ~60 MB. Zero external database dependencies.

Comparison with existing systems

| | Todo Apps | Session Notes | Kanban APIs | AgenticPlanning | |:---|:---:|:---:|:---:|:---:| | Goal hierarchy | None | None | Flat lists | Unlimited depth | | Decision preservation | None | Text only | None | Full crystallization | | Shadow paths | None | None | None | Yes | | Commitment tracking | None | None | Basic | Weighted + entangled | | Progress physics | None | None | None | Momentum + gravity | | Portability | Vendor-locked | File-based | API-locked | Single file | | External dependencies | Cloud service | None | Cloud service | None | | Counterfactual analysis | No | No | No | Yes | | Dream simulation | No | No | No | Yes | | Federation | No | No | No | Yes |

---

Why AgenticPlanning

Planning is a graph, not a checklist. When you trace why you're working on a task, you traverse a chain: task

Install

One-liner (desktop profile, backwards-compatible):

curl -fsSL https://agentralabs.tech/install/planning | bash

Downloads a pre-built agentic-planning-mcp binary to ~/.local/bin/ and merges the MCP server into your Claude Desktop and Claude Code configs. Intentions default to ~/.strategy.aplan. Requires curl and jq.

Environment profiles (one command per environment):

# Desktop MCP clients (auto-merge Claude Desktop + Claude Code when detected)
curl -fsSL https://agentralabs.tech/install/planning/desktop | bash

# Terminal-only (no desktop config writes)
curl -fsSL https://agentralabs.tech/install/planning/terminal | bash

# Remote/server hosts (no desktop config writes)
curl -fsSL https://agentralabs.tech/install/planning/server | bash

| Channel | Command | Result | |:---|:---|:---| | GitHub installer (official) | curl -fsSL https://agentralabs.tech/install/planning \| bash | Installs release binaries; merges MCP config | | crates.io paired crates (official) | cargo install agentic-planning-cli agentic-planning-mcp | Installs aplan and agentic-planning-mcp | | PyPI (SDK) | pip install agentic-planning | Python SDK | | npm (wasm) | npm install @agenticamem/planning | WASM-based planning SDK for Node.js and browser |

| Goal | Command | |:---|:---| | Just give me planning | Run the one-liner above | | Python developer | pip install agentic-planning | | Rust developer | cargo install agentic-planning-cli agentic-planning-mcp |

Detailed install options

Python SDK (requires aplan Rust binary):

pip install agentic-planning

Rust CLI + MCP:

cargo install agentic-planning-cli       # CLI (aplan)
cargo install agentic-planning-mcp       # MCP server

Rust library:

cargo add agentic-planning

Deployment Model

• Standalone by default: AgenticPlanning is independently installable and operable. Integration with AgenticMemory, AgenticTime, or AgenticContract is optional, never required.
• Bridges available: Optional bridge crate connects planning state to memory, time, contract, and identity systems.

| Area | Default behavior | Controls | |:---|:---|:---| | File path | ~/.strategy.aplan | --file /path/to/strategy.aplan | | Auth token | Read from AGENTIC_AUTH_TOKEN | Bearer auth on MCP server | | Output format | Text | --format json, --format table, --json | | Server mode | stdio | --mode http --port 3000 |

---

MCP Server

Any MCP-compatible client gets instant access to persistent planning state. The agentic-planning-mcp crate exposes the full PlanningEngine over the Model Context Protocol (JSON-RPC 2.0 over stdio).

cargo install agentic-planning-mcp

Configure Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "agentic-planning": {
      "command": "agentic-planning-mcp",
      "args": []
    }
  }
}

> Zero-config: defaults to ~/.strategy.aplan. Override with "args": ["--file", "/path/to/strategy.aplan"].

Configure VS Code / Cursor

Add to .vscode/settings.json:

{
  "mcp.servers": {
    "agentic-planning": {
      "command": "agentic-planning-mcp",
      "args": []
    }
  }
}

What the LLM gets

| Category | Count | Examples | |:---|---:|:---| | Tools | 13 | planning_goal, planning_decision, planning_commitment, planning_progress, planning_singularity, planning_dream, planning_counterfactual, planning_chain ... | | Resources | 9 | planning://goals, planning://decisions, planning://commitments, planning://singularity, planning://status ... | | Prompts | 4 | planning_review, goal_decomposition, decision_analysis, commitment_check |

Once connected, the LLM can create goals, crystallize decisions, track commitments, compute progress physics, collapse the intention singularity, and maintain strategic continuity — all backed by the same .aplan binary file. [Full MCP docs ->](crates/agentic-planning-mcp/README.md)

---

Quickstart

Strategic planning in 5 commands

# Create a goal
aplan goal create "Ship v2.0" --intention "Complete architecture rewrite"

# Add a decision fork
aplan decision create --goal g-001 --question "Which runtime?" \
  --option "Tokio — mature, large ecosystem" \
  --option "async-std — simpler API"

# Crystallize the decision
aplan decision crystallize d-001 --chosen 0 --reasoning "Team has Tokio experience"

# Make a commitment
aplan commitment create --goal g-001 --promise "Demo by Friday" --stakeholder "team-lead"

# View the full strategic state
aplan singularity --file strategy.aplan

Python SDK

from agentic_planning import PlanningGraph

planner = PlanningGraph("strategy.aplan")

# Create goals
planner.create_goal("Ship v2.0", intention="Complete rewrite")

# List all goals
goals = planner.list_goals()

Cross-session continuity

# Session 1: plan
aplan goal create "Migrate to Rust" --intention "Performance and safety"
aplan decision create --goal g-001 --question "Incremental or full rewrite?"

# Session 47 — months later, different LLM, same file:
aplan goal list                          # All goals preserved
aplan singularity --file strategy.aplan  # Full strategic state
aplan decision shadows d-001             # See what was NOT chosen

---

Common Workflows

1. Review strategic state — Get the full picture before a planning session:

``bash aplan singularity --file strategy.aplan # Collapse everything into one view aplan goal tree # See the goal hierarchy ``

1. Trace a decision chain — Understand how you got here:

``bash aplan chain trace d-001 # Walk the reasoning chain backward aplan chain cascade d-001 # See downstream effects ``

1. Check commitment health — Before taking on more work:

``bash aplan commitment due-soon # What's coming up? aplan commitment at-risk # What might slip? aplan commitment inventory # Full commitment load ``

1. Run a counterfactual — Explore

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: agentralabs
• Source: agentralabs/agentic-planning
• License: MIT

Install and usage instructions live in the source repository linked above.