<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)"
            srcset="docs/hero/planexe-hero-v1-grid-dark.svg">
    <img src="docs/hero/planexe-hero-v1-grid-light.svg"
         alt="The PlanExe icon is the P character and E character"
         width="100%">
  </picture>
</p>

<p align="center">
  <strong>Turn your idea into a comprehensive plan in minutes, not months.</strong>
</p>

<p align="center">
  <a href="https://app.mach-ai.com/planexe_early_access">
    <img src="https://img.shields.io/badge/%F0%9F%9A%80%20Try%20PlanExe%20in%20your%20browser-Generate%20a%20free%20plan-2ea44f?style=for-the-badge" alt="Try PlanExe in your browser — generate a free plan" height="48">
  </a>
</p>

<p align="center">
  Describe your idea, hit submit, and PlanExe returns a ~40-page plan in about 15 minutes.
</p>

<p align="center">
  <a href="https://home.planexe.org/"><strong>Create an account</strong></a> &nbsp;|&nbsp;
  <a href="https://planexe.org/examples/"><strong>See example plans</strong></a> &nbsp;|&nbsp;
  <a href="https://docs.planexe.org/getting_started/"><strong>Getting started guide</strong></a>
</p>

---

## Example plans generated with PlanExe

- A business plan for a [Minecraft-themed escape room](https://planexe.org/20251016_minecraft_escape_report.html).
- A business plan for a [Faraday cage manufacturing company](https://planexe.org/20250720_faraday_enclosure_report.html).
- A pilot project for a [Human as-a Service](https://planexe.org/20251012_human_as_a_service_protocol_report.html).
- See more [examples here](https://planexe.org/examples/).

## What is PlanExe?

PlanExe is an open-source tool and the premier planning tool for AI agents. It turns a single plain-english goal statement into a 40-page, strategic plan in ~15 minutes using local or cloud models. It's an accelerator for outlines, but no silver bullet for polished plans.

Typical output contains:

- Executive summary
- Gantt chart
- Governance structure
- Role descriptions
- Stakeholder maps
- Risk registers
- SWOT analyses

PlanExe produces well-structured, domain-aware output: correct terminology, logical task sequencing, and coherent sections. For technical topics (engineering programs, regulated industries), it often gets the vocabulary and structure right. Think of it as a first-draft scaffold that gives you something concrete to critique and refine.

However, the output has consistent weaknesses that matter: budgets are assumed rather than derived, timeline estimates are not grounded in real resource constraints, risk mitigations tend toward generic advice, and legal/regulatory details are plausible-sounding but unverified. The output should be treated as a structured starting point, not a deliverable. How much work it saves depends heavily on the project. For brainstorming or a first outline, it can save hours. For a client-ready plan, expect significant rework on every number, timeline, and risk section.

---

## Model Context Protocol (MCP)

PlanExe exposes an MCP server for AI agents at [https://mcp.planexe.org/](https://mcp.planexe.org/)

Assuming you have an MCP-compatible client ([Claude](https://docs.planexe.org/mcp/claude/), [Cursor](https://docs.planexe.org/mcp/cursor/), [Codex](https://docs.planexe.org/mcp/codex/), [LM Studio](https://docs.planexe.org/mcp/lm_studio/), [Windsurf](https://docs.planexe.org/mcp/windsurf/), OpenClaw, [Antigravity](https://docs.planexe.org/mcp/antigravity/)).

The Tool workflow

1. `example_plans` (optional, preview what PlanExe output looks like)
2. `example_prompts`
3. `model_profiles` (optional, helps choose `model_profile`)
4. non-tool step: draft/approve prompt
5. `plan_create`
6. `plan_status` (poll every 5 minutes until done)
7. optional if failed: `plan_retry`
8. download the result via `plan_file_info`

Concurrency note: each `plan_create` call returns a new `plan_id`; server-side global per-client concurrency is not capped, so clients should track their own parallel plans.

### Option A: Remote MCP (fastest path)

#### Prerequisites

- An account at [https://home.planexe.org](https://home.planexe.org).
- Sufficient funds to create plans.
- A PlanExe API key (`pex_...`) from your account

Use this endpoint directly in your MCP client:

```json
{
  "mcpServers": {
    "planexe": {
      "url": "https://mcp.planexe.org/mcp",
      "headers": {
        "X-API-Key": "pex_your_api_key_here"
      }
    }
  }
}
```

### Option B: Run MCP server locally with Docker

#### Prerequisites

- Docker
- OpenRouter account
- Create a PlanExe `.env` file with `OPENROUTER_API_KEY`.

Start the full stack:

```bash
docker compose up --build
```

Make sure that you can create plans in the web interface, before proceeding to MCP.

Then connect your client to:

- `http://localhost:8001/mcp`

For local docker defaults, auth is disabled in `docker-compose.yml`.

### MCP docs

- Setup overview: [https://docs.planexe.org/mcp/mcp_setup/](https://docs.planexe.org/mcp/mcp_setup/)
- Tool details and flow: [https://docs.planexe.org/mcp/mcp_details/](https://docs.planexe.org/mcp/mcp_details/)
- Claude: [https://docs.planexe.org/mcp/claude/](https://docs.planexe.org/mcp/claude/)
- Cursor: [https://docs.planexe.org/mcp/cursor/](https://docs.planexe.org/mcp/cursor/)
- Codex: [https://docs.planexe.org/mcp/codex/](https://docs.planexe.org/mcp/codex/)
- PlanExe MCP interface: [https://docs.planexe.org/mcp/planexe_mcp_interface/](https://docs.planexe.org/mcp/planexe_mcp_interface/)
- MCP Registry publishing metadata (`server.json`): `mcp_cloud/server.json`
- `llms.txt`: [https://mcp.planexe.org/llms.txt](https://mcp.planexe.org/llms.txt)

---

## Running the Pipeline via CLI (no frontend)

If you have a local Python environment set up and want to invoke the pipeline
directly — without the Flask UI — use the `planexe` CLI script at
the repo root.

```bash
# Create a plan from a text prompt
./planexe create_plan \
    --plan-text "Small coffee shop in Copenhagen, Denmark" \
    --output-dir ./planexe-outputs/1984-12-31/MyCoffeeShop_v1

# Or: read the plan prompt from a file
./planexe create_plan \
    --plan-file my_plan.txt \
    --output-dir ./planexe-outputs/1984-12-31/MyCoffeeShop_v1
```

The script creates the run directory if it does not exist and writes:

| File | Contents |
|---|---|
| `start_time.json` | `{"server_iso_utc": "<current UTC ISO timestamp>"}` |
| `plan.txt` | The plain-text plan prompt |

---

## For AI Agents

PlanExe is designed as infrastructure for AI agents. If you are an AI agent reading this:

- **Discovery:** Read [`public/llms.txt`](public/llms.txt) for service metadata, MCP tools, and endpoints.
- **MCP endpoint:** `https://mcp.planexe.org/mcp` — connect with an API key from [home.planexe.org](https://home.planexe.org/).
- **Workflow:** Call `example_prompts` to learn the expected prompt format, draft a detailed prompt (~300-800 words of flowing prose), then call `plan_create`.
- **Agent guide:** See [`docs/mcp/autonomous_agent_guide.md`](docs/mcp/autonomous_agent_guide.md) for the complete autonomous workflow.
- **Key outputs in zip:** `wbs_level1.json` (work packages), `wbs_level2.json` (tasks), `pre_project_assessment.json` (feasibility).

---

<details>
<summary><strong> Run locally with Docker (Click to expand)</strong></summary>

<br>

**Prerequisite:** Docker with Docker Compose installed; you only need basic [Docker](https://en.wikipedia.org/wiki/Docker_(software)) knowledge. No local Python setup is required because everything runs in containers.

### Follow these steps

1. Clone the repo and enter it:

```bash
git clone https://github.com/PlanExeOrg/PlanExe.git
cd PlanExe
```

2. Provide an LLM provider. Copy `.env.docker-example` to `.env` and fill in `OPENROUTER_API_KEY` with your key from [OpenRouter](https://openrouter.ai/). The containers mount `.env` and `llm_config/`; pick a model profile there. For host-side Ollama, use the `docker-ollama-llama3.1` entry and ensure Ollama is listening on `http://host.docker.internal:11434`.

3. Start the stack (first run builds the images):

```bash
docker compose up worker_plan frontend_multi_user
```

   The worker listens on http://localhost:8000 and the UI comes up on http://localhost:5001 after the Postgres and worker healthchecks pass.

4. Open http://localhost:5001 in your browser, create an account (or log in with the admin credentials from `.env`), enter your idea, and watch progress with:

```bash
docker compose logs -f worker_plan
```

   Outputs are written to `run/` on the host (mounted into both containers).

5. Stop with `Ctrl+C` (or `docker compose down`). Rebuild after code/dependency changes:

```bash
docker compose build --no-cache worker_plan frontend_multi_user
```

For compose tips, alternate ports, or troubleshooting, see `docs/docker.md` or `docker-compose.md`.

### Configuration

**Config A:** Run a model in the cloud using a paid provider. Follow the instructions in [OpenRouter](https://docs.planexe.org/ai_providers/openrouter/).

**Config B:** Run models locally on a high-end computer. Follow the instructions for either [Ollama](https://docs.planexe.org/ai_providers/ollama/) or [LM Studio](https://docs.planexe.org/ai_providers/lm_studio/). When using host-side tools with Docker, point the model URL at the host (for example `http://host.docker.internal:11434` for Ollama).

Recommendation: I recommend **Config A** as it offers the most straightforward path to getting PlanExe working reliably.

</details>

---

<details>
<summary><strong> Help (Click to expand)</strong></summary>

<br>

For help or feedback.

Join the [PlanExe Discord](https://planexe.org/discord).

</details>
