Get Started

Documentation

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

Epismo is a collaboration layer for work shared by people and AI agents. Reusable process and knowledge live in packs. Active work lives in tracks. The CLI, HTTP API, and MCP server expose the same underlying model, so local workflows, CI jobs, product integrations, and agent clients can all work from the same source of truth.

This documentation is written for a first-time reader. Before jumping into individual commands or endpoints, read this page and Core concepts to understand which object to create, how private sharing works, and which interface fits your use case.

The basic model

Epismo stores two kinds of information.

Information Epismo object Example Use it when
Reusable knowledge or process Pack Release review playbook, repository onboarding notes People or agents will reuse it later
Active work Track Review API docs, ship docs v1 It has status, due dates, owners, dependencies, or progress

Use this decision rule:

  • If the content should be reused, create a pack.
  • If the item should move toward completion, create a track.
  • If it is a repeatable procedure, create a workflow pack.
  • If it is reusable reference material, create a context pack.
  • If it is a concrete unit of work, create a task track.
  • If it is an outcome with progress, create a goal track.

Try it in five minutes

The CLI is the fastest way to learn the model.

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

Create a context pack for reusable onboarding notes.

epismo pack create --type context --title "Repo onboarding" --personal \
  --blocks '[{"title":"Layout","content":"The repo is organized around apps/, server/, and protobuf/."},{"title":"Local setup","content":"Run npm install, then start the services you need."}]'

Give the returned pack ID an alias so humans and agents can refer to it without copying a UUID.

epismo alias upsert @repo-onboarding --type context --id <pack-id>
epismo pack get @repo-onboarding --full

Now create active work as a task track.

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 flow covers the core Epismo loop: save reusable knowledge as packs, then manage execution as tracks.

Pick an interface

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, internal agents, and other MCP clients MCP server

Start with the CLI if you are unsure. CLI payloads are close to API request bodies, so a JSON example that works locally is usually a good starting point for an integration.

Object model

Object Purpose Main fields Notes
Workflow pack Repeatable procedure steps[] Steps can have title, content, assignee, and dependencies.
Context pack Reusable reference blocks blocks[] Good for repo notes, policies, research summaries, and examples.
Task track Concrete unit of work task.status, dueDate, assignee, dependsOn Task statuses are backlog, todo, in_progress, and 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.

Sharing and permissions

Private data lives either in personal space or in one or more workspace projects.

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

Create and update operations use scope. Search operations use scopes so you can search multiple private locations at once. Use sharedWith when a private item should also be visible to specific user IDs or emails.

Shared conventions

  • Dates use YYYY-MM-DD. Empty string clears an optional date.
  • Markdown content fields accept up to 65,535 characters.
  • Titles are required and max 255 characters.
  • Updates use PATCH semantics unless a page states otherwise. Omitted fields stay unchanged.
  • The CLI and API return JSON. CLI JSON goes to stdout; warnings and errors go to stderr.
  1. Read Core concepts for object selection, sharing, and workspace behavior.
  2. Use CLI reference to create and search packs and tracks.
  3. Move to API reference when building a product integration.
  4. Read MCP server when connecting an agent client.

Sections