clawpm

Multi-project task and research management (JSON-first CLI)

install

source · Clone the upstream repo

git clone https://github.com/malphas-gh/clawpm

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/malphas-gh/clawpm "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/clawpm" ~/.claude/skills/malphas-gh-clawpm-clawpm && rm -rf "$T"

manifest: skills/clawpm/SKILL.md

source content

ClawPM Skill

Multi-project task management. All commands emit JSON by default; use

-f text

for human-readable output.

First-Time Setup

clawpm setup               # Creates ~/clawpm/ with portfolio.toml, projects/, work_log.jsonl
clawpm setup --check       # Verify installation

Creating Projects

Projects are directories with a

.project/

folder. They don't need to be git repos.

Initialize in any directory

cd /path/to/my-project
clawpm project init                    # Auto-detects ID/name from directory
clawpm project init --id myproj        # Custom ID

From a git clone (auto-init)

Git repos under

~/clawpm/projects/

auto-initialize on first use:

git clone git@github.com:user/repo.git ~/clawpm/projects/repo
cd ~/clawpm/projects/repo
clawpm add "First task"    # Auto-initializes .project/, then adds task

Discover untracked repos

clawpm projects list --all   # Shows tracked + untracked git repos

Quick Start

# From a project directory (auto-detected):
clawpm status              # See project status
clawpm next                # Get next task
clawpm start 42            # Start task (short ID works)
clawpm done 42             # Mark done

# Or set a project context:
clawpm use my-project
clawpm status              # Now uses my-project

Top-Level Commands (Shortcuts)

Command	Equivalent	Description
`clawpm add "Title"`	`clawpm tasks add -t "Title"`	Quick add a task
`clawpm add "Title" -b "desc"`	`clawpm tasks add -t "Title" -b "desc"`	Add with body
`clawpm add "Title" --parent 25`	-	Add subtask
`clawpm done 42`	`clawpm tasks state 42 done`	Mark task done
`clawpm start 42`	`clawpm tasks state 42 progress`	Start working
`clawpm block 42`	`clawpm tasks state 42 blocked`	Mark blocked
`clawpm next`	`clawpm projects next`	Get next task
`clawpm status`	-	Project overview
`clawpm context`	-	Full agent context
`clawpm use <id>`	-	Set project context

Project Auto-Detection

ClawPM automatically detects your project from (in priority order):

Subcommand flag:
```
clawpm tasks list --project clawpm
```
Global flag:
```
clawpm --project clawpm status
```
Current directory: Walks up looking for
```
.project/settings.toml
```
Auto-init: If in untracked git repo under project_roots, auto-initializes
Context: Previously set with
```
clawpm use <project>
```

Short Task IDs

You can use just the numeric part of a task ID:

```
42
```
→
```
CLAWP-042
```
(prefix derived from project ID)
```
CLAWP-042
```
→
```
CLAWP-042
```
(full ID works too)

Subtasks

clawpm add "Subtask" --parent 25   # Creates subtask (auto-splits parent if needed)
clawpm tasks split 25              # Manually convert task to parent directory

clawpm done 25             # Fails if subtasks not done
clawpm done 25 --force     # Override and complete anyway

Subtasks move with parent on state change (done/blocked moves entire directory).

Agent Context (Resuming Work)

Get everything needed to resume work in one command:

clawpm context             # Full context for current project
clawpm context -p myproj   # Specific project

Returns JSON with: project info + spec, in-progress/next task, blockers, recent work log, git status, open issues.

Workflow Example

clawpm context             # Get full context
clawpm start 42            # Mark in progress (auto-logs)
# ... do work ...
git add . && git commit -m "feat: ..."
clawpm done 42 --note "Completed"       # Auto-logs with files_changed
clawpm log commit                        # Also log the git commits themselves

Hit a blocker:

clawpm block 42 --note "Need API credentials"

Full Command Reference

Projects

clawpm projects list [--all]            # List projects (--all includes untracked repos)
clawpm projects next                    # Next task across all projects
clawpm project context [project]        # Full project context
clawpm project init                     # Initialize project in current dir

Tasks

clawpm tasks                            # List tasks (default: open+progress+blocked)
clawpm tasks list [-s open|done|blocked|progress|all] [--flat]
clawpm tasks show <id>                  # Task details
clawpm tasks add -t "Title" [--priority 3] [--complexity m] [--parent <id>] [-b "body"]
clawpm tasks edit <id> [--title "..."] [--priority N] [--complexity s|m|l|xl] [--body "..."]
clawpm tasks state <id> open|progress|done|blocked [--note "..."] [--force]
clawpm tasks split <id>                 # Convert to parent directory for subtasks

Work Log

clawpm log add --task <id> --action progress --summary "What I did"
clawpm log tail [--limit 10]            # Recent entries (auto-filtered to current project)
clawpm log tail --all                   # Recent entries across all projects
clawpm log tail --follow                # Live tail (like tail -f)
clawpm log last                         # Most recent entry (auto-filtered to current project)
clawpm log last --all                   # Most recent entry across all projects
clawpm log commit [-n 10]               # Log recent git commits to work log
clawpm log commit --dry-run             # Preview without logging
clawpm log commit --task <id>           # Associate commits with a task

Note: State changes (start/done/block) auto-log to work_log with git files_changed.

Research

clawpm research list
clawpm research add --type investigation --title "Question"
clawpm research link --id <research_id> --session-key <key>

Issues

clawpm issues add --type bug --severity high --actual "What happened"
clawpm issues list [--open]             # Open issues only

Admin

clawpm setup               # Create portfolio (first-time)
clawpm setup --check       # Verify installation
clawpm status              # Project overview
clawpm context             # Full agent context
clawpm doctor              # Health check
clawpm use [project]       # Set/show project context
clawpm use --clear         # Clear context

Work Log Actions

```
start
```
- Started working (auto-logged on
```
clawpm start
```
)
```
progress
```
- Made progress
```
done
```
- Completed (auto-logged on
```
clawpm done
```
)
```
blocked
```
- Hit a blocker (auto-logged on
```
clawpm block
```
)
```
commit
```
- Git commit (logged via
```
clawpm log commit
```
)
```
pause
```
- Switching tasks
```
research
```
- Research note
```
note
```
- General observation

Task States & File Locations

State	File Pattern	Meaning
open	`tasks/CLAWP-042.md`	Ready to work
progress	`tasks/CLAWP-042.progress.md`	In progress
done	`tasks/done/CLAWP-042.md`	Completed
blocked	`tasks/blocked/CLAWP-042.md`	Waiting

Tips

Flag order:

clawpm [global flags] <command> [command flags]

— e.g.

clawpm -f text tasks list -s open

JSON output: All commands emit JSON by default; use
```
-f text
```
for human-readable
One command per call: Don't chain clawpm commands with
```
&&
```
— run each separately
Portfolio root: Default
```
~/clawpm
```
Work log: Append-only at
```
<portfolio>/work_log.jsonl
```

Troubleshooting

clawpm doctor              # Check for issues
clawpm setup --check       # Verify installation
clawpm log tail            # See recent activity