Your first project.
Four steps to the board.

STEP 01

Prepare your tools.

Use Node.js 24, Git, the GitHub CLI, and Claude Code. Planestro is developed on macOS; Linux runs its test suite. Windows is untried.

Install from Node.js, Git, GitHub CLI, and Claude Code. Configure your Git name and email if this machine has not made a commit before.

node --version  # Expect v24.x
git --version
gh auth login --scopes workflow
gh auth status
claude --version

STEP 02

Install Planestro.

Clone it beside the projects you’ll manage. These commands install the dependencies and build the local web interface.

git clone https://github.com/gravesisme/planestro
cd planestro
npm install
npm run build

Ready when: the build completes and your terminal is inside the planestro checkout.

GitHub returns “repository not found” without access to the private repository. Public availability is forthcoming.

STEP 03

Connect a project.

Planestro needs a Git repository with an initial commit. For live work, it also needs a GitHub remote you can push to and CI that runs on both the base branch and pull requests.

# Run from your Planestro checkout. Use a new, empty sibling directory.
mkdir ../myproject
cd ../myproject
git init -b main
mkdir -p .github/workflows
cat > package.json <<'JSON'
{
  "name": "myproject",
  "private": true,
  "type": "module",
  "scripts": { "test": "node --test" }
}
JSON
cat > greeting.js <<'JS'
export const greet = (name) => `Hello, ${name}!`;
JS
cat > greeting.test.js <<'JS'
import test from 'node:test';
import assert from 'node:assert/strict';
import { greet } from './greeting.js';
test('greets a person', () => {
  assert.equal(greet('Harrison'), 'Hello, Harrison!');
});
JS
cat > .github/workflows/ci.yml <<'YAML'
name: CI
on: [push, pull_request]
permissions:
  contents: read
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 24
      - run: npm test
YAML
cat > AGENTS.md <<'TEXT'
This is a small Node.js project. Run npm test before reporting completion.
Keep changes focused on the requested behavior and cover it with tests.
TEXT
cp AGENTS.md CLAUDE.md
npm test
git add .
git commit -m "Initialize project with a tested greeting"
cd ../planestro

# Creates a private GitHub repository on your account and pushes the initial commit.
# Choose another repository name if myproject already exists.
(cd ../myproject && gh repo create myproject --private --source=. --remote=origin --push)

Already have a project? Substitute its path for ../myproject. Confirm its remote, passing CI, and base branch; replace main below if it uses another branch. Put its build and test instructions in its own CLAUDE.md / AGENTS.md.

Give planning files their own home.

Use a separate Git repository so your backlog and decision history stay apart from your application code. Keep the planning directory private; it can contain internal requirements and activity.

# Run from your Planestro checkout; planning files stay outside the code repo.
git init ../myproject-planning
npm run planestro -- init ../myproject-planning --repo ../myproject --name "My Project" --prefix MP --default-branch main

Ready when: myproject-planning contains planestro.yml, an initial Git commit, and directories for items, prompts, and activity. The engine starts in dry-run.

STEP 04

Open your board.

npm start -- ../myproject-planning --open

Open http://127.0.0.1:4300 if a browser does not open automatically. Keep this terminal running; Ctrl+C stops the server.

1. Check Settings. Confirm the project’s base branch, keep engine.mode in dry-run, and check that the configured Claude model IDs are available to your account. Confirm Claude Code is signed in on this machine and review per-item budgets before enabling live work.
2. Try the lifecycle. Queue a clearly labeled trial item, approve its simulated plan, and read the Console’s “Would …” entries. Dry-run uses fake agents, Git, and GitHub. It changes the planning data, but does not implement changes in your project.
3. Start real work deliberately. Once GitHub authentication and base CI are green, switch engine.mode to live. Create a new item for your actual task; a completed dry-run item is only a simulation.
4. Queue, review, approve. For the starter above, try “Trim whitespace from the name before greeting it, with a regression test.” Queue it, review the plan, then choose Approve & implement. Planestro drives implementation, the PR, CI, merge, and cleanup; answer any requests in the board.

If port 4300 is occupied, choose another with --port 4301. For a missing model or expired credential, check Settings and the Console before retrying.

OPTIONAL / NO AGENT LOGIN

Just try the workflow.

After installing Planestro, the fictional Tidepool project lets you explore without a GitHub project or an agent login. Node and Git are still needed to install Planestro.

npm run sample

Open http://127.0.0.1:4310. Queue the sample bug, approve its plan, and watch it reach Done. Everything runs on in-memory fakes. Stop it with Ctrl+C.

npm run sample -- --reset rebuilds the sample, replacing its previous demo state. It does not reset your own project.

OPTIONAL / A MIXED FLEET

Add Codex as an implementer.

Install the Codex CLI and authenticate locally:

codex login
codex login status

Sign in to the Codex CLI with your ChatGPT account. Planestro uses the credentials available to that local CLI. See OpenAI’s authentication guide for supported authentication and automation guidance.

In Settings → Models, add a model with runner Codex (implements only), a unique ID such as codex-code, and a description such as “Implement code and tests.” Set a Codex model ID supported by your CLI, or leave it empty for its default. Choose it as the item’s implementer; keep Claude as planner.

Claude workers use a permission policy and can park for approval. Codex workers run inside a sandbox with no network access for commands; they report a block if the work needs an unavailable capability. Both use your repository’s instructions.