Documentation

Learn Epismo from the core model through the CLI, HTTP API, and MCP server.

Epismo is a shared workspace for the work that people and AI agents do together. As teams hand more of their work to agents, two things keep getting lost: the knowledge an agent needs to act well, and the live status of the work itself. Epismo gives both a home.

Reusable knowledge and process live in packs. A pack is something you save once and reuse many times: an onboarding guide, a review checklist, a research summary, a runbook.
Active work lives in tracks. A track is something with a status that moves toward completion: a task, or a goal with progress.

The same model is available through three interfaces (the CLI, the HTTP API, and the MCP server), so your terminal, your CI pipeline, your product backend, and your AI assistants all read and write the same source of truth. Nothing is locked into one tool.

If you are new to Epismo, read this page and then Core concepts. Together they answer the three questions most people have on day one: what should I create, who can see it, and which interface should I use?

The basic model

Almost everything in Epismo is either reusable knowledge or active work. Deciding which one you have is the first skill to learn.

If you have...	Create	Why	Example
Reusable knowledge or process	Pack	People or agents will reuse it later	Release-review checklist, new-hire onboarding guide
Active work	Track	It has status, due dates, owners, dependencies, or progress	"Review the pricing page", "Ship onboarding v2"

A quick rule of thumb:

Will you reuse the content later? Create a pack.
Does the item need to reach "done"? Create a track.
A repeatable procedure → a workflow pack. Reference material → a context pack.
A concrete piece of work → a task track. An outcome you track progress toward → a goal track.

Try it in five minutes

The CLI is the fastest way to feel how the model works. Install it and sign in:

npm install -g epismo
epismo login --email you@example.com
epismo whoami

Save some reusable knowledge as a context pack. Each block is a named section of reference material:

epismo pack create --type context --title "Team onboarding" --personal \
  --blocks '[{"title":"Where things live","content":"Docs in Notion, code in GitHub, designs in Figma."},{"title":"How we work","content":"Weekly planning on Mondays; ship behind feature flags."}]'

Give the returned pack ID an alias so you and your agents can refer to it by a readable name instead of a raw UUID:

epismo alias upsert @team-onboarding --id $PACK_ID
epismo pack get @team-onboarding --full

Now create some active work as a task track, then find it again with search:

epismo track create --type task --title "Review docs structure" --personal \
  --task '{"status":"todo","dueDate":"2026-06-05"}'
 
epismo track search --type task --personal --filter '{"status":["todo"]}'

That is the core Epismo loop: capture reusable knowledge as packs, then drive execution as tracks.

Pick an interface

All three interfaces speak the same object model. Choose by where the work happens.

Interface	Best for	Read
CLI	Local work, operations, CI, quick validation	CLI reference
HTTP API	Product integrations and backend services	API reference
MCP server	ChatGPT, Claude, and other AI agents and MCP clients	MCP server

If you are unsure, start with the CLI. Its inputs are very close to API request bodies, so a JSON example that works in your terminal is usually a good starting point for an integration.

Object model

These are the building blocks you will work with everywhere in Epismo.

Object	Purpose	Main fields	Notes
Workflow pack	Repeatable procedure	`steps[]`	Each step can have a title, content, assignee, and dependencies.
Context pack	Reusable reference blocks	`blocks[]`	Good for onboarding guides, policies, research, and examples.
Task track	Concrete unit of work	`task.status`, `dueDate`, `assignee`, `dependsOn`	Statuses: `backlog`, `todo`, `in_progress`, `done`.
Goal track	Outcome with progress	`goal.status`, `progress`, `dueDate`	Progress is an integer from 0 to 100.
Alias	Human-readable pack reference	`@name`, `@handle/name`	Aliases point to packs, not tracks.

Who can see your data

Private data lives in one of two places: your personal space, or one or more projects inside a workspace. You choose the location with scope.

Keep something to yourself:

{ "scope": { "type": "personal" } }

Share it with a team through a project:

{ "scope": { "type": "projects", "ids": ["project-id"] } }

Two details worth remembering early:

Create and update calls take a single scope. Search calls take scopes (plural) so you can look across several private locations at once.
Use sharedWith to also expose a private item to specific people by user ID or email.

Core concepts covers workspaces, projects, and sharing in full.

Conventions used throughout

A few rules hold across every interface, so the examples in these docs stay consistent:

Dates use YYYY-MM-DD. An empty string clears an optional date.
Markdown content fields accept up to 65,535 characters; titles are required and capped at 255.
Updates use PATCH semantics unless a page says otherwise: fields you omit keep their current value.
Responses are JSON. In the CLI, results go to stdout and warnings or errors go to stderr.