CatPilot is a terminal-first personal operating system for GitHub Copilot CLI users who want one place to capture tasks, journal notes, milestones, memos, summaries, and reports without leaving the command line.
It can be used in three ways:
| Entry Point | Best For | What You Get |
|---|---|---|
catpilot |
Full Copilot CLI experience | CatPilot as a Copilot plugin with agent + skills for tasks, journal, milestones, memos, summaries, and reports |
cat-pilot |
Direct terminal workflows | Standalone CLI for setup, diagnostics, tasks, journal entries, and memos |
cat-tui |
Visual browsing in the terminal | Experimental dashboard for browsing the same workspace data through a terminal UI |
Most terminal tools are either too raw or too rigid. CatPilot is meant to feel closer to a practical daily assistant:
- Capture a task the second it appears
- Turn a rough idea into a SMART task (goal, measure, steps, why) without filling in a form
- See everything through an Eisenhower Matrix and get a ranked answer to "what now?"
- Keep lightweight work notes without opening another app
- Create handoff memos and meeting summaries as markdown files
- Keep Copilot-aware workflows connected to the same storage
- Move between chat, direct CLI, and terminal dashboard without losing context
All interfaces write to the same config-driven storage, so your data stays in sync.
CatPilot is more than a CLI tool β it's a two-layer second brain:
- Layer 1 β this repo (public, generic): the engine, agent, skills, and a real MCP server. Neutral vocabulary only (tasks, journal, learning, growth, projects) so it's safe to open-source and use with any employer.
- Layer 2 β your private vault (outside the repo): your real content, ideally an Obsidian vault. CatPilot writes here; the repo only ships templates, never data.
Run cat-pilot setup once to point storage.root at your Obsidian vault. It writes a
global config (~/.catpilot/config.json) so the same brain is reachable from
any directory, through four doors:
| Surface | How | Best for |
|---|---|---|
| GitHub Copilot CLI | copilot plugin install + agent/skills |
Conversational planning, summaries, reports |
| GitHub Copilot Canvas | copilot plugin install catpilot-canvas@awesome-copilot (renders in the GitHub Copilot app side panel) |
Visual dashboard, tasks board, reports, timeline, charts |
| Copilot in VS Code | .vscode/mcp.json (MCP server) |
Editor + Obsidian side by side |
| Copilot App | plugin + MCP registration | Session-based planning |
| Standalone CLI / MCP | cat-pilot / catpilot-mcp |
Scripting & embedding anywhere |
New personal-management domains help you stay on track for projects, certifications, studies, and growth/review prep:
knowledgeβ a foldered, tagged Knowledge Base (evolved from memos): organize notes into folders, connect them with tags (which feed the Obsidian graph), and browse them in the canvas with Grid / List / Folders / By-month views, search, and a full markdown editor. Legacy flatmemos/notes stay readable. Tools:kb_add,kb_list,kb_read,kb_update,kb_remove,kb_folders,kb_move(memo_*kept as aliases).learningβ certification & study paths: a goal + ordered steps with progress derived from step completion, target dates, spaced reviews, and an achievement recorded on completion. Copilot can draft a whole path for you. Steps are kept separate from your main tasks. Tools:learning_path_add/list/read/complete,learning_step_add/update.projectsβ richer than a status line: an index plus items (requirements / tasks / milestones), optional linked main tasks and linked milestones, achievements, and derived progress β with an "Ask Copilot about this project" button that grounds suggestions in the project's plan. Tools:project_create,project_read,project_item_add/update,project_complete,project_board.achievementsβ a dedicated log of wins, auto-recorded when a learning path or project completes (and addable manually), surfaced on the Learning and Project dashboards. Tools:achievement_add,achievement_list.growthβ accomplishment / brag-doc log + neutral review-prep summaries.pomodoroβ focus timers with configurable focus/short-break/long-break durations (default 25/5/15, set inconfig.json/ setup / canvas settings) modeled as timestamp + duration, so a running session is consistent across the CLI, MCP and canvas and survives process restarts; sessions can optionally link to a task and are logged to a partitionedpomodoro.mdhistory. Includes productivity reports (by session/day/week/task) measuring completed focus sessions, focus minutes, and completion rate.sanitizeβ a pre-write guardrail that flags employer-internal details before they ever hit disk, so growth/review content stays shareable.
A title tells you that something needs doing; it rarely tells you how to start. Every CatPilot task therefore carries optional SMART details:
| Field | SMART | The question it answers |
|---|---|---|
goal |
Specific | What exactly does "done" look like? |
measure |
Measurable | How will you know it worked? |
steps |
Achievable | What are the first concrete steps? |
why |
Relevant | Why does this matter right now? |
dueDate |
Time-bound | When does it need to be done? |
Nothing is mandatory β the title is still the only required field. CatPilot coaches rather than interrogates: it saves the task first, then asks at most two or three short questions with examples, and shows a live 0β5 quality score.
Those fields (plus the due date and priority) feed an Eisenhower Matrix:
| Urgent | Not Urgent | |
|---|---|---|
| Important | π₯ Q1 Β· Do now | ποΈ Q2 Β· Schedule |
| Not Important | π€ Q3 Β· Delegate or batch | π§ Q4 Β· Drop or do later |
Classification is deterministic first, Copilot on demand: urgency comes from the due date
(overdue / today / within 3 days) or a P0, importance from priority, a linked project, or the
presence of a why / measure. Anything you set explicitly always wins, and every automatic
placement carries a one-line rationale so it's never a black box.
# capture with SMART details, or let the coach walk you through it
cat-pilot task add "Ship the v2 export endpoint" --due 2026-04-10 --priority P1 \
--goal "v2 export live behind a feature flag" \
--measure "p95 < 300ms on staging, export tests green" \
--why "Unblocks the Q3 reporting milestone"
cat-pilot task add "Rework the onboarding email" --guided # interactive SMART coach
cat-pilot task smart 12 # view / edit a task's SMART details
cat-pilot task matrix # the four quadrants, grouped by deadline
cat-pilot task matrix --quadrant q2 # just "Schedule"
cat-pilot task focus --limit 5 # ranked "what to do next" + a reason each
cat-pilot task list --quadrant q1
cat-pilot task carry # bring open tasks forward from an earlier monthCatPilot files tasks by period (month, by default), so unfinished work stays in the period it
was created in. task list tells you when open tasks are sitting in an earlier period, and
task carry (or the banner on the canvas Tasks page) moves them into the current one β the
SMART details and progress log travel with them, and completed tasks stay where they were
finished.
In chat, just ask: "what should I work on?", "triage my tasks", "plan my day" β the
prioritization-coach skill reads the matrix, proposes changes with reasons, and only
applies them once you confirm. MCP/adapter tools: task_smart_set, task_matrix, task_focus,
task_carry.
π Start here:
docs/INSTALL.md Β·
docs/SURFACES.md Β·
docs/USING_IN_VSCODE.md Β·
docs/OBSIDIAN_KNOWLEDGE_BASE.md Β·
docs/PRIVACY_AND_BOUNDARIES.md Β·
docs/PLAYBOOK.md
CatPilot ships a GitHub Copilot canvas extension β a beautiful, modern side-panel UI that turns your whole workspace into a visual command center, without leaving the Copilot app. It reads and writes the exact same config-driven storage as the CLI, agent, and MCP server, so everything stays in sync across surfaces.
The extension lives in .github/extensions/catpilot-canvas/
and renders in the GitHub Copilot app side panel β
just ask Copilot to "open the CatPilot canvas" and it appears next to your chat. It's also
published to the Awesome Copilot marketplace
so anyone can install it in one command (see Install the canvas below).
What you get in the canvas:
- Dashboard β hero, summary cards, last-3-days activity, charts, and productivity nudges.
- Tasks β switch between list (table), board (kanban), calendar and π― Eisenhower Matrix views. The board has Backlog Β· Overdue Β· To do Β· In Progress Β· Blocked Β· Done; the matrix has four colored quadrant panels (Do now Β· Schedule Β· Delegate or batch Β· Drop or later) with Overdue / Today / Next 7 days / Later groups and drag-and-drop between quadrants to pin a task's importance/urgency. The task modal has a collapsible π― Make it SMART section with a live 0β5 quality meter and an β¨ Build with Copilot popup that drafts every field from a plain-language description. Toolbar adds π― Focus plan and π§ Triage with Copilot. Pick a status (To do / In Progress / Blocked / Done) on create/edit, filter by due date (All Β· Today Β· 7 days), complete inline, drag between columns, edit/save locally, and open a detail popup β plus an add button.
- Knowledge β a foldered, tagged Knowledge Base (evolved memos) with a stats header, folder + tag filter rails, Grid / List / Folders / By-month views, search, and a detail popup that renders markdown and has a full editor (write/preview) with Save/Delete and folder/tag editing.
- Journal & Milestones β browse, add, and open full detail views. Milestones can be linked to a project or learning path and filtered by that link.
- Learning β certification/study paths with a progress dashboard, filters, a step checklist you can toggle, achievements, and β¨ Generate with Copilot path drafting.
- Projects β a portfolio grid plus a project dashboard (timeline, requirements, tasks, milestones, linked tasks/milestones, achievements) and an Ask Copilot about this project button for grounded suggestions.
- Growth β card views with add buttons and detail popups.
- Pomodoro β a live countdown ring for the running session, start controls (type + minutes + optional task picker), complete/cancel, a today stats strip, a recent-sessions table, and a Productivity section with a period/grouping selector, focus-minutes bar chart, completion donut, and grouped table β all backed by the same files the CLI/MCP use. Session durations are editable from Settings.
- Reports β generate GitHub Copilot executive reports for any period (this week, last
month, all timeβ¦), open them (markdown or HTML), and delete. Shares the same reports folder
as the
report-generatorskill. - Timeline β a 7/14/30-day activity rail grouped by day, with quick agent actions to summarize or plan from what you've been working on.
- Settings β change your storage root, partitioning, or migration mode from an interactive wizard: preview exactly which files would move, then an approval checkbox gates Confirm & apply so nothing is migrated until you say so.
- Help β an in-canvas capabilities guide explaining every view.
- Markdown everywhere β every text field has a formatting toolbar (bold, italic, headings, lists, checkboxes, code, links), a live preview toggle, and β¨ Generate with Copilot.
- Ask Copilot β a global β¨ button to hand off any prompt to the agent from the canvas.
- Onboarding β a first-run setup flow when no CatPilot config exists yet.
- Light / dark β a theme toggle that follows the Copilot app theme tokens.
Every action round-trips through CatPilot's storage engine, so the agent, skills, and MCP server all see the same data instantly.
Pick whichever fits how you work β all four end up in the same visual canvas:
| Method | When to use | Steps |
|---|---|---|
| Awesome Copilot marketplace (recommended) | You want it in every repo/session with one command | copilot plugin install catpilot-canvas@awesome-copilot |
| Project-scoped (zero install) | You've cloned tanure/cat-copilot |
Nothing to do β it's auto-discovered from .github/extensions/catpilot-canvas/ |
| User-scoped | You want it available globally without the marketplace | Copy the catpilot-canvas/ folder into ~/.copilot/extensions/ (or $COPILOT_HOME/extensions/) |
| Gist | Someone shared it with you | Copilot palette β Install extension from gistβ¦ |
If the Awesome Copilot marketplace isn't registered yet, add it once, then install:
copilot plugin marketplace add github/awesome-copilot
copilot plugin install catpilot-canvas@awesome-copilotThe canvas UI is rendered by the GitHub Copilot app's canvas panel. From either surface:
- GitHub Copilot app β open a session in a repo where the extension is installed and ask Copilot to "open the CatPilot canvas" (or click it from the canvas picker). The dashboard opens in the side panel.
- GitHub Copilot CLI β run
copilotin your project; the CLI discovers and loads the extension, so its agent actions (generate a report, summarize the timeline, add a task, etc.) are available right away in the terminal. The visual canvas itself is drawn by the app's canvas renderer, so when you ask Copilot to open it, it surfaces in the connected app panel β there is no separate ASCII/terminal renderer for canvases. For a terminal-only dashboard, usecat-tuiinstead.
All screenshots below come from a throwaway demo vault (
tools/seed-demo-vault.mjs) β every task, name and date in them is invented.
1 Β· Dashboard β where you land. Counts, today's focus, charts and the last few days of activity. The quick buttons in the hero add a task, journal entry or milestone without leaving the page.
2 Β· Tasks β four ways to look at the same work. The switcher in the top right flips
between β° List, β¦ Board, π
Calendar and π― Matrix. Nothing is duplicated:
they are all views over the same tasks.md, so a change in one shows up everywhere,
including in the CLI.
The list adds a Quadrant column, so you can see where each task sits at a glance.
An auto marker means CatPilot inferred the quadrant; without it, you pinned it yourself.
The board is a kanban over Backlog Β· Overdue Β· To do Β· In Progress Β· Blocked Β· Done. Drag a card to change its status. (Done has no quick-add button β finished work is something you move into, not something you create.)
3 Β· π― Eisenhower Matrix β decide what actually deserves your day. Four quadrants, each grouped by Overdue / Today / Next 7 days / Later, with a coaching strip that tells you when the balance is off (too much firefighting, nothing scheduled, and so on).
- Drag a card between quadrants to pin its importance/urgency β that writes back to the
task, and the CLI will agree with you next time you run
cat-pilot task matrix. - οΌ on a quadrant header creates a task already tagged for that quadrant.
- π― Focus plan gives you a ranked "what next" list with a reason per task.
- π§ Triage with Copilot asks the agent to classify anything still unset.
4 Β· SMART details β make a task you can actually start. Open any task and the detail popup shows its goal, measure, steps and why, the quadrant it landed in and the reason it landed there, plus a 0β5 quality meter. Every SMART field is optional; a title is still the only thing CatPilot requires.
5 Β· β¨ Build with Copilot β describe it roughly, get a SMART task. In the task form, click β¨ Build with Copilot, write one or two plain sentences, and press Draft it. Copilot fills in goal, measure, steps, why, a realistic due date, priority, tags and the Eisenhower axes. Then you choose:
- β Create this task β save it as-is.
- βοΈ Edit first β open it in the normal task form with everything pre-filled.
- π Try again β reword the description and re-draft.
Nothing is written to disk until you pick one.
If no Copilot session is attached, the popup degrades gracefully: it shows a copy-able prompt and a paste Copilot's answer box, so a draft produced anywhere β the chat panel, the Copilot app, the CLI β can still become a task.
6 Β· Carry work forward when the month rolls over. CatPilot partitions storage by period,
so on the 1st of a month your open tasks are still filed under the previous one. The Tasks
page notices and shows a banner offering to move them across β or run
cat-pilot task carry from the terminal. Completed tasks stay where they were, and the
progress log follows the task.
Try it yourself without touching your own data:
node tools/seed-demo-vault.mjs # prints a config path, invented data only
CATPILOT_CONFIG=<that path> node tools/demo-canvas.mjs
# then open http://127.0.0.1:4173/Choose this if you want CatPilot to work inside GitHub Copilot CLI with agent-driven prompts and skills.
You get:
- Tasks
- Journal entries
- Milestones
- Memos
- Daily summaries
- Executive reports
- Interactive setup through Copilot chat
Choose this if you want direct shell commands without going through Copilot chat.
You get:
- Setup and diagnostics
- Task management
- Journal capture
- Memo creation and listing
- An experimental TUI that reads the same data
Choose this if you want a quick visual read of your workspace data.
Today, cat-tui is a separate executable, not something embedded inside Copilot CLI. It renders a useful dashboard, but it should be treated as an early preview rather than a fully interactive app.
| Capability | catpilot Copilot Plugin |
cat-pilot CLI |
cat-tui |
|---|---|---|---|
| Interactive setup | Yes | Yes | No |
| Plugin diagnostics | Yes | Partial | No |
| Workspace diagnostics | No | Yes | No |
| Add task | Yes | Yes | Preview only |
| List tasks | Yes | Yes | Yes |
| Complete task | Yes | Yes | Preview only |
| Remove task | Yes | Yes | Preview only |
| SMART task details | Yes | Yes | No |
| Eisenhower Matrix | Yes | Yes | No |
| Focus plan / triage | Yes | Yes | No |
| Add journal entry | Yes | Yes | No |
| List journal entries | Yes | Yes | Yes |
| Create memo | Yes | Yes | No |
| List memos | Yes | Yes | Yes |
| Read memo content | Yes | No | No |
| Milestones | Yes | No | No |
| Pomodoro timer (start/stop/status) | Yes | Yes | No |
| Pomodoro history & stats | Yes | Yes | No |
| Pomodoro productivity reports | Yes | Yes | No |
| Configurable Pomodoro durations | Yes | Yes | No |
| Daily summaries | Yes | No | No |
| Executive reports | Yes | No | No |
- Node.js 18+
- npm
- GitHub Copilot CLI in
PATHonly if you want the plugin experience
CatPilot is published as a Copilot plugin marketplace, so it's discoverable from the Copilot CLI and the Copilot App:
npm install -g @alberttanure/catpilot-cli
# Discover + install via the CatPilot marketplace (recommended)
copilot plugin marketplace add tanure/cat-copilot
copilot plugin marketplace browse catpilot-marketplace
copilot plugin install catpilot@catpilot-marketplace
copilot agentsPrefer a direct install? copilot plugin install tanure/cat-copilot works too.
Note: copilot plugin install ... registers CatPilot inside Copilot CLI only.
If you also want direct shell commands like cat-pilot and cat-tui, run the global npm install step as shown below.
Expected result: CatPilot appears in the Copilot agents list.
Then start chat:
copilot chatExample prompts:
Set up CatPilot for this workspace.
Add a task to prepare my weekly review with priority high.
Create a milestone for the internal demo by 2026-03-31.
Summarize my day and save it.
Generate an executive report for this month in markdown.
npm install -g @alberttanure/catpilot-cli
cat-pilot setupOnce setup is complete, you can work directly from the shell:
cat-pilot task add "Prepare weekly review" --due 2026-03-21 --priority P1
cat-pilot journal add "Met with the team and aligned on next steps."
cat-pilot memo create "handover-notes" --content "Key decisions, blockers, and owners."
cat-tuiCatPilot stores a shared global configuration at ~/.catpilot/config.json, so the
same storage is used no matter which directory you launch from. Run setup once:
cat-pilot setupPrefer non-interactive? Pass flags:
cat-pilot setup --yes --root "/path/to/your/ObsidianVault" --partitioning monthResolution order (first match wins): CATPILOT_CONFIG env β CATPILOT_ROOT env β
<cwd>/data/config.json (project-local, use cat-pilot setup --local) β
~/.catpilot/config.json (global). cat-pilot doctor shows which one is active.
Setup guides you through:
- storage root path
- partitioning mode
- migration mode for existing files
Default template shape:
{
"version": 1,
"storage": {
"root": "data",
"partitioning": "month",
"allowExternalPaths": true,
"files": {
"tasks": "tasks.md",
"journal": "journal.md",
"milestones": "milestones.md",
"memos": "memos"
}
},
"migration": {
"mode": "move"
}
}Use the CLI when you already know what you want to capture.
cat-pilot task add "Review open customer issues" --priority P1
cat-pilot task add "Draft platform update for leadership" --due 2026-03-19 --priority P0
cat-pilot task list --status allCapture decisions while they are fresh.
cat-pilot journal add "Decided to split release prep into docs, QA, and publish steps."
cat-pilot memo create "release-handoff" --content "Owners: Docs, QA, Publish. Risks: timing and npm validation."Use the plugin path when you want richer help.
Summarize what I completed today.
Turn my notes into a handoff memo.
Show me overdue tasks and propose next actions.
Generate a weekly report in markdown.
Use the TUI when you want a fast visual scan of the same files.
cat-tuiSample dashboard output:
π± CatPilot Β· Terminal Dashboard
ββββββββββββββββββββββββββββββββββββββββββββββββββ
π Tasks: 4 total
> π’ #7 Analyze meeting outcomes | Due: 2026-03-12 | High
π’ #8 Create deployment plan | Due: 2026-03-13 | High
π’ #11 Share outcomes with the team | Due: 2026-03-12 | High
βΉοΈ β
Ready | β β: navigate | a: add | d: delete | e: edit | ESC: exit
Note: the TUI currently works best as a dashboard and browser. It renders correctly and reads real data, but its input handling is still early.
cat-pilot setup
cat-pilot doctorcat-pilot task add "Draft Q2 planning notes" --due 2026-03-25 --priority P1 --tags planning,leadership --context "Need first draft before leadership sync"
cat-pilot task add "Waiting on legal sign-off" --status Blocked
cat-pilot task list
cat-pilot task list --status all
cat-pilot task list --status blocked
cat-pilot task block 12
cat-pilot task unblock 12
cat-pilot task complete 12
cat-pilot task remove 12# SMART flags on capture (all optional)
cat-pilot task add "Ship the v2 export endpoint" --due 2026-04-10 --priority P1 \
--goal "v2 export live behind a feature flag" \
--measure "p95 < 300ms on staging, export tests green" \
--why "Unblocks the Q3 reporting milestone" \
--steps "Draft schema -> implement -> test -> roll out" \
--importance high --urgency low
cat-pilot task add "Rework the onboarding email" --guided # interactive SMART coach
cat-pilot task smart 12 # show a task's SMART details + score
cat-pilot task smart 12 --measure "NPS +5" # edit one field
cat-pilot task smart 12 --guided # coach an existing task
cat-pilot task smart 12 --urgency auto # unpin an axis, go back to auto-derive
cat-pilot task matrix # four quadrants, grouped by deadline
cat-pilot task matrix --quadrant q1 --status all
cat-pilot task matrix --json
cat-pilot task focus --limit 5 # ranked next actions with a reason each
cat-pilot task list --quadrant q2
cat-pilot task carry --dry-run # preview what would move forward
cat-pilot task carry # move open tasks into the current period
cat-pilot task carry --ids 4,12 # just these twocat-pilot journal add "Focused in the morning, blocked by approvals in the afternoon."
cat-pilot journal list
cat-pilot journal list --days 14cat-pilot memo create "team-retro" --content "Wins, blockers, and next actions."
cat-pilot memo listThese are examples for Copilot chat, not standalone CLI commands:
Add a task to draft Q2 planning notes with priority high.
Create milestone Launch internal demo target 2026-03-31.
Create memo title Team Retrospective with notes about wins and blockers.
Summarize my day and save it.
Generate executive report for this month in markdown.
There are two doctor commands, and they serve different purposes.
Use this when CatPilot is not showing up inside Copilot CLI.
catpilot doctorIt checks:
- packaged plugin assets
plugin.json- agent file discovery
copilot --versionavailability
Use this when your local workspace commands or storage setup are not behaving correctly.
cat-pilot doctorIt checks:
- the active config (global
~/.catpilot/config.jsonor project-local) and its scope - the resolved storage root
- packaged
plugin.json - packaged
agents/ - packaged
skills/ - workspace root and plugin root paths
cat-pilot doctor
catpilot doctor
catpilot updateThen restart your terminal and verify:
copilot agentsIf needed, run with debug enabled:
CATPILOT_DEBUG=1 catpilotOn PowerShell:
$env:CATPILOT_DEBUG=1
catpilotCatPilot uses config-driven file storage. The plugin, CLI, and TUI all point to the same workspace files.
That means:
- add a task with
cat-pilot, see it incat-tui - create a memo in Copilot chat, list it with
cat-pilot memo list - capture notes from chat or shell without splitting your system into separate silos
This shared-storage model is what makes the multi-client workflow practical in real day-to-day use.
cat-pilot task add "Prepare architecture review" --priority P0 --due 2026-03-20
cat-pilot task add "Write follow-up memo" --priority P2
cat-pilot journal add "Architecture review moved to Thursday. Need updated deck."
cat-pilot memo create "architecture-review" --content "Open questions, decision log, and follow-up owners."
cat-pilot task list --status all
cat-tuiReview my open tasks and propose the top 3 priorities for today.
Turn my journal notes from this week into a concise status update.
Create a memo for my handoff tomorrow.
Generate a monthly executive report in markdown.
- Main visual asset:
assets/catpilot-pixel.png - Alternative SVG asset:
assets/catpilot-pixel.svg - Canvas screenshots (demo data):
docs/images/ - Demo vault + standalone canvas server:
tools/seed-demo-vault.mjs,tools/demo-canvas.mjs - Deeper multi-client examples:
docs/MULTI_CLIENT_EXAMPLES.md - Compatibility notes:
docs/PHASE2-COMPATIBILITY.md - Release notes:
CHANGELOG.md
Recommended:
catpilot updateAlternative:
npm update -g @alberttanure/catpilot-cli- Current version: v0.4.0
- Changelog: CHANGELOG.md
- GitHub releases: Releases
MIT β see LICENSE.





