claudeers.
// Developer Tools

pilotage

A local cockpit for your Claude Code sessions, on your PC and your phone

// Developer Tools[ cli ][ api ][ desktop ][ web ][ mobile ][ claude ]#claude#agentic-coding#ai-agents#claude-ai#claude-code#codex#coding-agents#dashboard#devtools◷ MIT$open-sourceupdated 1 day ago

Install with your AI

Paste into Claude Code, Cursor, or any agent — it reads the repo and wires the tool into your project.

Install and set up pilotage (npm project) into my current project.
Found on https://claudeers.com/pilotage
Repo: https://github.com/Ya-zid/pilotage
Homepage/docs: —
Detected install method: npm → npm install pilotage-cli
Category: devtools. Platforms: cli, api, desktop, web, mobile.
Read the repo's README for exact setup and env vars, then install it and wire it into my project.

Claudeers Health Verdict:
unknown; community-verified: false. Confirm the source before running anything.
// or install directly (npm)
npm install pilotage-cli
// or clone
git clone https://github.com/Ya-zid/pilotage

// compatibility

Platformscli, api, desktop, web, mobile
Operating systems—
AI compatibilityclaude
LicenseMIT
Pricingopen-source
LanguageJavaScript

Get your FREE $2.50 API credits to access TickAtlas financial data ↗

Pilotage

A local web cockpit for everything you build with Claude Code (and Codex or Gemini CLI): your projects, what is running right now, AI summaries of your sessions, and a task list that fills itself.

Pilotage: Home shows what is waiting; yesterday's session is picked up and resumed with a new message

Pilotage reads the session transcripts your coding agents already write on your computer, groups them by project, and shows them in a web app you open on your PC or your phone. It never changes your projects or your agents' files.

Status: early. I built it for my own daily workflow (Claude Code all day) and use it every day. It runs on macOS, Linux and WSL2 + Windows (see Platforms); most of the daily use is on WSL2. Expect rough edges, and please report them.

Contents

What it does

PageWhat it's for
HomeAt a glance: what's working, what needs you, today's plan (AI-proposed, you pick) and a "pick up" list of work you can resume, one line each
SessionsEvery session from Claude Code, Codex and Gemini CLI, with running ones on top (Needs you · Working · Open). Read the conversation, resume or fork it, open it in the Claude app
TasksTo do · Doing · Done, plus Suggested: short to-dos the AI finds in your sessions, marked You or Claude. You keep or dismiss them; nothing lands on your board without you
ProjectsEvery git repo or project folder, grouped by workspace (top-level folder), with an AI summary, workstreams, sessions, worktrees, notes and docs (incl. Claude memory files)
IdeasYour captured ideas, plus possible projects the project scout spotted: a tool you built inside another project, or a project you said you'd like to build

Also: History (year heatmap, "what did I do that day / week"), Portfolio & CV (AI-written project entries, EN/FR), Spin off (turn part of a project into a new folder with a CLAUDE.md handoff written from your past sessions), and starting or resuming sessions from the browser or your phone (optionally answering Claude Code's "trust this folder?" for you, so a phone launch doesn't wait for someone at the PC).

  • Multi-harness. Claude Code (~/.claude, and the Windows-side ~/.claude on WSL), Codex CLI (~/.codex) and Gemini CLI (~/.gemini) sessions all show up. More Claude config dirs (a second account) can be added in Settings.
  • AI summaries with a usage guard. Work is cut into blocks (a stretch of prompts without a 4-hour gap). Each block gets a short summary (Haiku by default), each project a summary and workstreams, each day a plan. Results are cached and only redone when their input changes.
  • Project scout. Now and then, one call per active project (Sonnet by default) looks for parts of your work that deserve their own project. Most runs find nothing, which is the intended outcome.
  • Phone access. Pair your phone with a QR code and use Pilotage over your home Wi-Fi or a VPN (NetBird, Tailscale). See docs/PHONE.md.
  • Live. Pages update by themselves (server-sent events); you never press refresh.
More screenshots (fictional demo data)

Pilotage on the PC and on a phone

Sessions pageA project page with summary, next steps and details
Tasks, Suggested tabIdeas with possible projects from the scout
Home on a phoneSessions on a phone

Quick start

npx pilotage-cli

That's it: Pilotage starts on http://127.0.0.1:4747 and opens in your browser with a one-time login. The first start indexes your existing sessions (a few seconds to a minute), then summarizes recent work in the background, within the AI limits.

To keep it and start it at login:

npm install -g pilotage-cli
pilotage install    # macOS: a login item. WSL: autostart at Windows login and a Desktop shortcut

Update with npm install -g pilotage-cli@latest && pilotage restart. Your data stays in ~/.pilotage.

For the phone, follow docs/PHONE.md (Settings → Phone & security, then pair with a QR code).

From source (to hack on it)
git clone https://github.com/Ya-zid/pilotage.git ~/pilotage
cd ~/pilotage
npm install
npm --prefix web install
bin/pilotage build      # builds the web app into web/dist
bin/pilotage            # starts the server and opens it in your browser
bin/pilotage install    # optional: `pilotage` on your PATH, plus autostart as above

A clone keeps its data in its own data/ folder.

Requirements

  • macOS, Linux, or Windows 10/11 with WSL2 (native Windows without WSL is not supported)
  • Node.js 22+ (nvm works; pilotage also looks in ~/.nvm, or set PILOTAGE_NODE)
  • Claude Code installed and logged in (for the default AI provider and for starting sessions). Codex and Gemini CLI are optional.
  • git, bash, curl
  • openssl, for HTTPS on the phone (plain HTTP works without it)

Platforms

macOSLinuxWSL2 + Windows
Sessions, projects, tasks, summaries, scout, historyyesyesyes
Start a session from the browsera Terminal window, or backgroundyour terminal emulator (in a desktop session), or backgrounda Windows Terminal tab, or background
Codex / Gemini sessionsread + start in a terminalread + start in a terminalread + start in a terminal tab
Open in VS Code / foldercode / Findercode / xdg-openVS Code / Explorer
Windows-side Claude Code historyn/an/ayes
Phone accessdirect bind with PILOTAGE_LAN_BIND, see docs/PHONE.mdsame as macOSWindows forwarder + firewall rule
pilotage installlogin item (LaunchAgent)none yet: add pilotage run to your startupautostart at Windows login, Desktop shortcut

Sessions started from the browser open where you'd type yourself, with Remote Control on, so they also show in the Claude app on your phone. On macOS that is Terminal (set PILOTAGE_TERMINAL=iTerm for iTerm). On Linux it's the first terminal found: x-terminal-emulator, GNOME Terminal, Konsole, kitty, Alacritty, WezTerm, Ghostty, foot, xterm and a few others, or the one in PILOTAGE_TERMINAL. Over SSH or with no desktop, sessions start in the background (claude --bg; type in one with claude attach <id>).

Most of the daily use is on WSL2, and macOS and Linux terminal launches are new in 0.3.0: reports are very welcome (see Contributing).

Commands

pilotage              # start if needed, then open in the browser
pilotage status       # running? phone forwarder? firewall rule? autostart?
pilotage version      # installed version, short commit, and the running server's version
pilotage open         # open in the browser (one-time login)
pilotage phone        # enable phone access (WSL: one Windows admin prompt)
pilotage pair         # QR code in the terminal to pair a phone
pilotage projects     # list projects            pilotage live   # what's running
pilotage new <project> [--bg] [--model sonnet] "first prompt"   # start a session (your agents can use this too)
pilotage restart | stop | logs | build
pilotage rotate-key   # replace the desktop key the CLI uses
pilotage uninstall    # remove autostart, shortcut, forwarder, command, firewall rule (keeps your data; --purge deletes it)

From a clone, use bin/pilotage until pilotage install puts the command on your PATH.

How it works and privacy

  • A small Node server (no framework) on 127.0.0.1:4747. It indexes transcripts read-only: ~/.claude, ~/.codex, ~/.gemini, your git repos (every git call uses --no-optional-locks, hooks off) and project folders under your home folder.
  • A React web app (Vite) served by that server. Every page and API call needs a paired device.
  • Pilotage writes only to its own data folder (state, caches, summaries, tokens: ~/.pilotage, or data/ in a clone), to new folders you explicitly create with Spin off / New project, and, if you run pilotage install, to ~/Library/LaunchAgents/local.pilotage.plist on macOS, or on WSL to a Startup entry, a Desktop shortcut and the phone forwarder in %LOCALAPPDATA%\Pilotage. One opt-in exception: with Settings → Trust folders (or the checkbox when starting a session), it answers Claude Code's "trust this folder?" for you, which sets one flag in ~/.claude.json (see SECURITY.md).
  • Nothing leaves your computer except AI calls, and those go to the provider you choose. By default that is your own claude -p (your Claude subscription), run with no tools, no MCP servers and no session files, in an empty sandbox folder. Common secret formats in prompts (API keys, tokens, private keys) are redacted before anything is stored or sent; the project scout also leaves out any prompt that mentions a password. Passwords typed in plain words elsewhere are not detected, so the summaries see what your sessions saw.
  • Pilotage listens on 127.0.0.1 only, every request needs a paired device (or the CLI's key), pairing codes are one-time, and PC-only actions are refused from phones. Details and the threat model: SECURITY.md.

For contributors, docs/ARCHITECTURE.md shows how requests and data flow through the code.

Configuration

Almost everything is in Settings (saved in state.json in the data folder): your name (used in the greeting and in what the AI writes; defaults to your git user.name), AI provider and models, usage limits, extra folders to scan, hidden folders, workspace names, launch defaults (permission mode, model, terminal or background), theme.

Environment variables:

VariableDefaultWhat it does
PILOTAGE_PORT4747Port for the PC browser and the CLI
PILOTAGE_LAN_INTERNAL_PORTPORT - 1Loopback port the phone forwarder targets
PILOTAGE_LAN_PORT4748Port phones connect to (the forwarder on Windows, or the direct bind)
PILOTAGE_LAN_BINDunsetLinux/macOS: address the phone listener binds directly (e.g. 0.0.0.0). Unset = no phone access outside WSL
PILOTAGE_LAN_ALLOWlan,vpnWith PILOTAGE_LAN_BIND: who may connect (lan, vpn, IPv4 CIDRs, comma-separated)
PILOTAGE_DATA~/.pilotage (./data in a clone)Where state, caches, summaries and tokens live
PILOTAGE_TERMINALautomacOS: the app sessions open in (Terminal, iTerm). Linux: the terminal emulator (kitty, /usr/bin/foot…). none = always in the background
PILOTAGE_NO_AIunset1 = never call an AI provider
PILOTAGE_NO_FORWARDERunset1 = don't start the Windows phone forwarder
PILOTAGE_NO_RELAY_WATCHunset1 = WSL: don't re-open the listeners when Windows loses its connection to them
PILOTAGE_WSLdetected0 / 1 to force the platform detection
PILOTAGE_WIN_HOMEdetectedYour Windows profile seen from WSL (/mnt/c/Users/<you>)
PILOTAGE_OPENSSLopensslThe openssl binary used to create the phone HTTPS certificates
PILOTAGE_NODEdetectedNode.js binary for bin/pilotage
CODEX_HOME~/.codexCodex CLI's own setting; Pilotage reads Codex sessions from there

Workspaces are the top-level folders under your home (~/acme/api and ~/acme/web are both in "acme"). Rename them in Settings. To fold one top folder into another workspace, add "workspaces": {"acme-old": {"mergeInto": "acme"}} to data/state.json while Pilotage is stopped.

AI cost and usage

By default every AI call is a headless claude -p on your Claude subscription: Haiku for session summaries, project summaries and today's plan, Sonnet for CV entries and the project scout. You can pick other models, or another provider in Settings → AI: Codex CLI (codex exec), or any OpenAI-compatible API (DeepSeek, OpenRouter, OpenAI, Groq, local Ollama). API keys are stored only in data/secrets.json (mode 600) and never shown again.

Guards, all adjustable in Settings → AI:

  • Pilotage caps its own calls: 500 per 5 hours and 1,500 per day (non-Claude providers: 300 a day).
  • Automatic work pauses above 60% of your 5-hour limit and above 92% of your weekly limit. Claude Code passes those numbers (rate_limits) to your statusline command; Pilotage reads them from ~/.claude/rate_limits.json, which a statusline script can save (example below). Without that file only the call caps apply.
  • Summaries are cached and only redone when the work changes. The first run on a long history is the expensive one: it summarizes your recent sessions, a few at a time.
  • Turn AI off entirely in Settings, or start the server with PILOTAGE_NO_AI=1.
A statusline script that saves the usage numbers

~/.claude/statusline.py, enabled with "statusLine": {"type": "command", "command": "python3 ~/.claude/statusline.py"} in ~/.claude/settings.json:

#!/usr/bin/env python3
import json, os, sys, time
data = json.load(sys.stdin)
rl = data.get("rate_limits")
if rl:  # {"five_hour": {"used_percentage", "resets_at"}, "seven_day": {...}}
    p = os.path.expanduser("~/.claude/rate_limits.json")
    with open(p + ".tmp", "w") as f:
        json.dump({"saved_at": int(time.time()), **rl}, f)
    os.replace(p + ".tmp", p)
print((data.get("model") or {}).get("display_name", ""))

Phone access

Pair a phone from Settings → Devices → Pair a phone (or pilotage pair) and use Pilotage over your home Wi-Fi or a VPN (NetBird, Tailscale). Nothing is reachable from the internet. On WSL2, a small forwarder on Windows lets phones in, only from your trusted Wi-Fi and VPN ranges; on Linux and macOS you turn on a direct bind with PILOTAGE_LAN_BIND. Pilotage can also serve HTTPS so the phone can install it as an app.

The full guide (pairing, HTTPS certificate on Android and iPhone, Linux/macOS setup, security notes): docs/PHONE.md.

FAQ

Does it send my code or transcripts anywhere? Only to the AI provider you configured, as short summaries of your prompts and the agent's final replies, with secrets redacted. With PILOTAGE_NO_AI=1, nothing.

Will it change my repos? No. It reads them. It only creates new folders when you ask (Spin off / New project).

Claude Code deleted my old transcripts. Claude Code removes transcripts after about 30 days by default. Pilotage keeps its summaries and reads ~/.claude/history.jsonl, so older work stays visible as "archived" sessions (prompts only).

Why is the first run slow or busy? It indexes every transcript once, then summarizes recent work in the background. Later runs only look at what changed.

Can I run it on a server? It is built for one person on their own computer. It binds to 127.0.0.1 on purpose.

Can I try it without my own data? Yes: scripts/demo/run-demo.sh builds a fictional world (projects, sessions, summaries, tasks) and starts Pilotage on it, with no AI calls and without touching your real Pilotage. See CONTRIBUTING.md.

Contributing

Contributions are welcome: bug reports, tests on Linux and macOS, documentation, fixes and features.

  • Start with CONTRIBUTING.md: setup, where things live, checks to run, and the ground rules (read-only toward your projects and agent folders, security stays tight, no personal data).
  • Looking for something to do? Try a good first issue.
  • Questions and ideas: Discussions. Bugs and feature requests: Issues.
  • How the code fits together: docs/ARCHITECTURE.md.
npm test                          # server tests (node:test): temp data dirs, no AI, no forwarder
cd web && npx tsc --noEmit -p .   # type-check the web app
npm run leak-scan                 # no personal data or secrets in what you commit

This project follows a Code of Conduct. It is a side project with one maintainer, so replies may take a while. Changes are listed in CHANGELOG.md.

Roadmap and help wanted

Directions where help is most useful, based on what the code does not do yet:

  • Testing on real machines. The maintainer works on WSL2. Install reports from macOS and Linux (what worked, what didn't) help most: terminal launches with your terminal app, the macOS login item, phone HTTPS with macOS's own openssl.
  • Linux autostart. pilotage install could set up a systemd user unit (bin/pilotage).
  • Phone access. IPv6 peers and IPv6 ranges in PILOTAGE_LAN_ALLOW are not supported yet (server/net.js).
  • More session sources. Codex and Gemini are adapters in server/sources/harness/; other coding agents could follow the same shape (harness/common.js describes it).
  • Tests. The web app has no automated tests yet.

Before starting on one of these, open an issue or a discussion so we can agree on the shape.

Security

Please report vulnerabilities privately through GitHub's private vulnerability reporting, not in a public issue. The threat model and how authentication works: SECURITY.md.

Not affiliated with Anthropic

Pilotage is an independent open-source project. It is not affiliated with, endorsed by or sponsored by Anthropic, OpenAI or Google. Claude and Claude Code are products of Anthropic; Codex is a product of OpenAI; Gemini CLI is a product of Google. Pilotage reads the files these tools write on your computer and runs their command-line tools.

License

MIT. Made by Yazid Slimani.

// faq

What is pilotage?

A local cockpit for your Claude Code sessions, on your PC and your phone. It is open-source on GitHub.

Is pilotage free to use?

pilotage is open-source under the MIT license, so it is free to use.

What category does pilotage belong to?

pilotage is listed under devtools in the Claudeers registry of Claude-compatible tools.

1 views
★ 13 stars
unclaimed
updated 1 day ago

// embed badge

pilotage on Claudeers
[![Claudeers](https://claudeers.com/api/badge/pilotage.svg)](https://claudeers.com/pilotage)

// retro hit counter

pilotage hit counter
[![Hits](https://claudeers.com/api/counter/pilotage.svg)](https://claudeers.com/pilotage)

// reviews

// guestbook

0/500

// related in Developer Tools

🔓

The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Curs…

// devtoolsaffaan-m/⟨JavaScript⟩★ 307,864◷ MIT[ claude ]
🔓

Makes your AI agent think like the laziest senior dev in the room. The best code is the code you never wrote.

// devtoolsDietrichGebert/⟨JavaScript⟩★ 187,728◷ MIT[ claude ]
🔓

AI coding assistant skill (Claude Code, Codex, OpenCode, Cursor, Gemini CLI, and more). Turn any folder of code, SQL schemas, R scripts, shell scripts, docs,…

// devtoolssafishamsi/⟨Python⟩★ 147,800◷ MIT[ claude ]
🔓

Use Garry Tan's exact Claude Code setup: 23 opinionated tools that serve as CEO, Designer, Eng Manager, Release Manager, Doc Engineer, and QA

// devtoolsgarrytan/⟨TypeScript⟩★ 140,465◷ MIT[ claude ]
→ see how pilotage connects across the ecosystem