CatPilot 😺

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

Why CatPilot

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
• 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.

A personal knowledge OS across every Copilot surface

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.

Point data/config.json's storage.root at your Obsidian vault and the same brain is reachable from four doors:

Surface	How	Best for
GitHub Copilot CLI	copilot plugin install + agent/skills	Conversational planning, summaries, reports
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:

• learning — certification & study tracker (goals, target dates, progress).
• growth — accomplishment / brag-doc log + neutral review-prep summaries.
• project-tracker — lightweight per-project status rollups.
• sanitize — a pre-write guardrail that flags employer-internal details before they ever hit disk, so growth/review content stays shareable.

📚 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

Choose Your Path

Option 1: Full Copilot Experience

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

Option 2: Standalone Terminal Workflow

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

Option 3: Terminal Dashboard Preview

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 Matrix

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
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
Daily summaries	Yes	No	No
Executive reports	Yes	No	No

Installation

Requirements

• Node.js 18+
• npm
• GitHub Copilot CLI in PATH only if you want the plugin experience

Install For The Full Copilot 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 agents

Prefer 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 chat

Example 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.

Install For Direct CLI And TUI Usage

npm install -g @alberttanure/catpilot-cli
cat-pilot setup

Once 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-tui

First-Time Setup

CatPilot stores its workspace configuration in data/config.json.

If you run:

cat-pilot setup

you will be guided 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"
   }
}

What Day-To-Day Use Looks Like

Morning Planning

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 all

During A Meeting

Capture 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."

End Of Day With Copilot

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.

Quick Visual Check

Use the TUI when you want a fast visual scan of the same files.

cat-tui

Sample 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.

Core Commands

Standalone CLI

Setup And Diagnostics

cat-pilot setup
cat-pilot doctor

Tasks

cat-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 list
cat-pilot task list --status all
cat-pilot task complete 12
cat-pilot task remove 12

Journal

cat-pilot journal add "Focused in the morning, blocked by approvals in the afternoon."
cat-pilot journal list
cat-pilot journal list --days 14

Memos

cat-pilot memo create "team-retro" --content "Wins, blockers, and next actions."
cat-pilot memo list

Copilot Plugin Flow

These 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.

Diagnostics And Troubleshooting

There are two doctor commands, and they serve different purposes.

catpilot doctor

Use this when CatPilot is not showing up inside Copilot CLI.

catpilot doctor

It checks:

• packaged plugin assets
• plugin.json
• agent file discovery
• copilot --version availability

cat-pilot doctor

Use this when your local workspace commands or storage setup are not behaving correctly.

cat-pilot doctor

It checks:

• workspace data/config.json
• packaged plugin.json
• packaged agents/
• packaged skills/
• workspace root and plugin root paths

Common Recovery Flow

cat-pilot doctor
catpilot doctor
catpilot update

Then restart your terminal and verify:

copilot agents

If needed, run with debug enabled:

CATPILOT_DEBUG=1 catpilot

On PowerShell:

$env:CATPILOT_DEBUG=1
catpilot

How The Interfaces Stay In Sync

CatPilot 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 in cat-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.

Practical Examples

Example: Run Your Day From The Terminal

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-tui

Example: Use Copilot For The Heavy Lifting

Review 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.

Screens, Assets, And Docs

• Main visual asset: assets/catpilot-pixel.png
• Alternative SVG asset: assets/catpilot-pixel.svg
• Deeper multi-client examples: docs/MULTI_CLIENT_EXAMPLES.md
• Compatibility notes: docs/PHASE2-COMPATIBILITY.md
• Release notes: CHANGELOG.md

Update

Recommended:

catpilot update

Alternative:

npm update -g @alberttanure/catpilot-cli

Release Notes

• Current version: v0.1.10
• Changelog: CHANGELOG.md
• GitHub releases: Releases

License

MIT — see LICENSE.