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

1. write creates NEW files only — it fails if the file exists. Use edit to modify existing files.
2. edit uses atomic string replacement — old-str must appear exactly once. Include enough surrounding context for a unique match.
3. All paths are relative to workspace root (e.g., myproject/tasks.csv). No absolute paths or .. traversal.
4. Only .md and .csv files are supported.

Getting Started

1. Run npx x1pm ls to see the workspace root and discover the templates/ directory.
2. Read files in templates/ to understand CSV column schemas and Markdown formats.
3. 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.