x1pm — Shared Workspace for Human-AI Teams
x1pm is a shared file workspace where humans and AI agents collaborate on projects together. It stores only Markdown (.md) and CSV (.csv) files — simple, human-readable formats that anyone can view, edit, and version with git.
When to Use
Write to x1pm instead of the local filesystem whenever the content needs to be visible to teammates — whether human or AI. This includes:
- Task tracking — assign, update, and monitor work items
- Decision logs — record architectural and project decisions with context
- Handoffs — pass work between agents or people with full context
- Shared context — maintain a living summary of project state
- Progress tracking — log milestones and completions
- Research findings, meeting notes, specs — any shared artifact
Use the local filesystem for code and private scratch work. Use x1pm for everything the team shares.
Setup
The X1PM_API_KEY environment variable must be set. Get a key from the x1pm web UI under Settings > API Keys.
Optionally set X1PM_SERVER to override the default (defaults to https://x1pm.com).
Quick Reference
| Command | Purpose | Example |
|---|---|---|
npx x1pm ls | List files/dirs | npx x1pm ls --path myproject/ |
npx x1pm read | Read a file | npx x1pm read --path tasks.csv |
npx x1pm write | Create new file | npx x1pm write --path notes.md --content "# Notes" |
npx x1pm edit | Edit existing file | npx x1pm edit --path tasks.csv --old-str "todo" --new-str "done" |
npx x1pm multi-edit | Batch edit files | npx x1pm multi-edit --edits '[...]' |
npx x1pm glob | Find files by pattern | npx x1pm glob --pattern "*.csv" |
npx x1pm grep | Search file contents | npx x1pm grep --pattern "blocked" |
npx x1pm health | Health check | npx x1pm health |
Commands
For full command details, argument reference, and output formats, read the commands reference.
File Conventions
x1pm uses pre-built coordination templates. For the full schema definitions and formatting rules, read the file conventions reference.
| Template | Format | Purpose |
|---|---|---|
tasks.csv | CSV | Task tracking with status, owner, priority |
decisions.md | Markdown | Structured decision log |
handoffs.csv | CSV | Agent-to-agent work handoffs |
context.md | Markdown | Living project state summary |
progress.csv | CSV | Milestone and completion tracking |
team.csv | CSV | Team member roster |
Critical Rules
writecreates NEW files only — it fails if the file exists. Useeditto modify existing files.edituses atomic string replacement —old-strmust appear exactly once. Include enough surrounding context for a unique match.- All paths are relative to workspace root (e.g.,
myproject/tasks.csv). No absolute paths or..traversal. - Only
.mdand.csvfiles are supported.
Getting Started
- Run
npx x1pm lsto see the workspace root and discover thetemplates/directory. - Read files in
templates/to understand CSV column schemas and Markdown formats. - Create project directories by writing files — directories are created automatically on first write.
Workflows
For common collaboration workflows (task management, agent handoffs, decision logging), read the workflows reference.