🏛️ Esedre (/eh-ˈseh-dreh/)

The open developer roadmap and ticketing engine engineered to provide long-term grounding for LLM agent context, powered by a fast CLI, local Web UI, and Model Context Protocol (MCP) server.

🌟 Overview

Esedre (with short CLI alias ese) is an open-source developer planning engine backed by plain text files (Markdown & JSON) that are easily version-controlled in git. Designed from the ground up for software engineers and autonomous LLM coding agents (such as Google Antigravity, Claude Code, and Cursor) to coordinate together, Esedre solves the single biggest bottleneck in LLM-assisted development: agent context drift and session amnesia.

⚓ Core Pillar: Long-Term Grounding for LLM Agent Context

LLM coding agents possess extraordinary implementation speed, but face a fundamental architectural ceiling: context windows fill up, compact, and reset between turns and sessions. External issue trackers live in distant web silos that agents cannot inspect reliably or locally without API keys and network overhead. Over multi-turn pair programming sessions, models lose track of architectural intent, past verification history, and upcoming milestones.

Esedre's core feature is providing persistent, authoritative long-term grounding to LLM agent context:

• Git-Backed Ground Truth: Tickets, feature breakdowns, architecture plans, and verification comments reside right alongside source code in git. They branch, merge, and stay synchronized with the codebase.
• First-Class MCP Integration: Through the official Model Context Protocol, LLM agents query roadmap priorities (esedre_list_tickets), inspect deep specifications (esedre_get_ticket), and update plans (esedre_save_plan) in real time.
• Cross-Session Memory & Grounding: When an LLM agent begins a new turn, recovers from a context compaction, or transitions across developer handoffs, Esedre grounds the model to concrete technical specifications, constraints, and upcoming milestones: preventing drift and hallucinated direction.
• Optimistic Concurrency Protection: Multi-agent pair-programming remains safe through SHA-1 content hash versioning, ensuring concurrent agents or developers never silently overwrite each other's work.

⚡ Key Capabilities

1. Long-Term LLM Agent Grounding: The primary architectural foundation: anchoring LLM agents to persistent project memory, architectural plans, and git-backed roadmap milestones across multi-turn sessions and context compactions.
2. CLI Commands (esedre / ese): List, query, plan, create, and update tickets via simple terminal commands with human-readable colored tables or machine-readable --json output.
3. Model Context Protocol (MCP) Server: Full JSON-RPC 2.0 stdio server implementing the official MCP specification (2024-11-05), exposing roadmap tickets as first-class tools and URI resources.
4. Agent Project Allow-List (Multi-Project Isolation): Informs each LLM agent only of the projects it is authorized to access, keeping unrelated project tickets, specifications, and plans completely isolated.
5. Optimistic Concurrency Control: SHA-1 content hashing on all tickets and plans, preventing concurrent agents or humans from clobbering each other's edits.
6. Local Web Dashboard & Embeddable Component: Run a visual dashboard with ese start to manage tickets in your browser, or embed <esedre-planner> into any web app without adding UI framework dependencies to your project.
7. Project Milestones & Umbrella Flags: Group tickets into release deliverables with real-time completion progress and umbrella feature flag propagation.

🏛️ About the Name

Origin

Esedre derives from classical Latin exedra (plural esedre), the semicircular architectural council pavilions where ancient architects, master builders, and planners gathered to debate designs, draft blueprints, and coordinate construction. That classical forum mirrors Esedre's mission: a structured, open workspace where developers and LLM coding partners collaborate to scope work, align on plans, and ship software.

Pronunciation Guide

Esedre is pronounced eh-SEH-dreh (phonetically: /ɛˈsɛ.drɛ/).

• Short CLI alias: ese (pronounced /ˈɛ.sɛ/).

🚀 Quick Start

1. Installation

# Global CLI installation (recommended)
npm install -g esedre

# Or run instantly without global installation via npx
npx esedre init

2. Initialize Your Project

Run ese init inside any project repository. It automatically configures .esedre/esedre.json, plants in-repo shell wrappers (.esedre/ese), configures MCP for LLM agents, and generates your initial snapshot:

ese init

# Or non-interactive with custom project code and display name:
ese init --project MYAPP --name "My App" -y

3. Start the Web UI & Server

# Start background server daemon on port 5674
ese start

# Open dashboard: http://localhost:5674/app

The server launches with unconstrained portfolio visibility across all registered data hubs and projects, allowing the main Esedre Web UI (as opposed to embedded component and LLM agent project-scoped behavior) to manage them seamlessly. Incoming agent requests enforce project scoping dynamically via the x-esedre-allowed-projects header or ?allowedProjects=... query parameter.

4. Create Your First Ticket

ese create --title "Build authentication flow" --type Feature --priority High
ese list
ese get 1

Multi-Project Tip: Passing "allowedProjects": ["*"] in .esedre/esedre.json authorizes access to all registered projects in the workspace.

💻 CLI Commands

Both esedre and ese can be used interchangeably. Commands are structured into semantic categories:

Roadmap Commands (Pair Programming & LLM Agents)

Core day-to-day workflow commands for scoping, viewing, planning, and verifying tickets:

| Command | Usage | Description | |---|---|---| | list | ese list [-p\|--project <code\|all>] [-s\|--status <status>] [-t\|--type <type>] [-P\|--priority <priority>] [-m\|--milestone <name>] [--blocked] [--linked-to <key>] [--json] | List roadmap tickets with optional filters. Defaults to the active project. | | get | ese get <id> [--json] | View ticket specifications, feature breakdown, comments, links, and SHA-1 hash. | | plan | ese plan <id> [--set "<markdown>"] [--file <path>] [--last-hash <h>] | Read or update the active implementation plan markdown. | | create | ese create --title "..." [-p\|--project <code>] [-t\|--type <type>] [-P\|--priority <priority>] [-m\|--milestone <name>] [--detail "<md>"] [--file <path>] | Create a new ticket with auto-sequential ID, optional priority, optional milestone, and specification markdown. Title strictly capped at 48 chars. | | update | ese update <id> [-s\|--status <status>] [-t\|--type <type>] [-P\|--priority <priority\|none>] [-m\|--milestone <name\|none>] [--title "..."] [--detail "<md>"] [--file <path>] [--last-hash <h>] | Update ticket status, type, priority, milestone, title, or specification markdown with optimistic concurrency protection. | | link | ese link <sourceId> <relation> <targetId> [--author "..."] | Establish a bi-directional link between two tickets. Relations: relates-to, blocks, parent-of, duplicates. | | unlink | ese unlink <sourceId> <targetId> [--relation <relation>] | Remove a bi-directional link between two tickets. | | milestone | ese milestone [list\|get\|create\|update\|delete] [args...] | Manage project milestones and umbrella feature flags with deliverables tracking. | | comment | ese comment <id> ["<text>"] [--file <path>] [--text "..."] [--author "..."] | Append a developer or LLM agent note to ticket history. | | snapshot, refresh | ese snapshot [--project <code>] [--json] | Generate or refresh projection .esedre/snapshot.json for zero-latency agent context. | | projects | ese projects [--json] | List registered projects within authorized scope. |

Service Daemon Commands

Manage the local web dashboard and API server:

| Command | Usage | Description | |---|---|---| | start | ese start [--port <n>] [--foreground \| -f] | Start the Esedre background server daemon (or foreground with -f). | | stop | ese stop [--port <n>] | Stop the running Esedre background server daemon. | | status | ese status [--port <n>] | Check health, uptime, and diagnostics of the running server. | | logs | ese logs [--port <n>] [--lines <n>] | Tail recent server output logs. | | mcp | ese mcp | Launch the Model Context Protocol stdio server for LLM agents. |

Developer Administration (Human Machine Setup)

Commands for repository onboarding, central machine linking, and maintenance:

| Command | Usage | Description | |---|---|---| | init | ese init [<path>] [--project <code>] [--name <name>] [--hub <name\|path>] [-y] | Bring a project repository online, bootstrap a dedicated data hub (--hub), or create a project directly in a data hub (--project <code>). | | configure | ese configure [add <path> \| remove <code\|path> \| set <k> <v>] | Inspect or mutate central configuration (~/.esedre/config.json). Link external project repositories or data hubs. | | rename-project | ese rename-project <oldCode> <newCode> [--name "<name>"] | Rename a project code across directory storage paths, manifests, and tickets. | | project set | ese project set <code> [--name "<name>"] | Update metadata for an existing project (e.g. display name). | | upgrade | ese upgrade [<path>] [--all \| -a] [--force \| -f] | Upgrade workspace configuration schema, in-repo wrappers, and agent skills across current or all registered workspaces. |

Human vs LLM Agent Workflows: Developer Administration commands (init, configure, upgrade) manage system-level repository linking and central machine configuration. They are intended for human developers during initial setup. Autonomous LLM coding partners operate within the authorized workspace scope using Roadmap and Service Daemon commands (list, get, plan, create, update, comment, snapshot, start, status).

Linking External Repositories vs Data Hub Projects

Esedre cleanly separates external repository linking from centralized data hub projects:

• Link Existing Repositories (ese configure add <repoPath>): Registers an external code repository in your central projects map (~/.esedre/config.json) for federated multi-repo workflows.
• Create Data Hub Projects (ese init --project <code> [--name "<name>"] [--hub <hub>]): Registers a non-development or standalone project directly inside your configured ticket data hub (dataDir). When multiple data hubs exist, pass --hub <name|path> to disambiguate.

Central Configuration & Hoisted Data Directories

Esedre employs a two-tier configuration model that cleanly isolates machine-specific paths from project repositories:

• Central Machine Configuration (~/.esedre/config.json): Configured via ese configure, this file holds user-level settings for your machine: registered ticket data hubs (dataDir, such as ../esedre-data), linked external repository paths (projects), and the default server port.
• Workspace Repository Configuration (.esedre/esedre.json): Project code repositories only need a lightweight descriptor declaring their projectCode and authorized allowedProjects scope.
• Smart Data Hub Inheritance: When dataDir is omitted from .esedre/esedre.json, Esedre automatically checks if your central data hub in ~/.esedre/config.json contains the project. If found, it inherits the hub path seamlessly. Different developers collaborating on the same codebase can maintain their ticket hubs in different filesystem locations without committing machine-specific relative paths to version control.
• Subdirectory Guard in ese init: Initializing a repository via ese init does not write dataDir to .esedre/esedre.json when the configured data hub is located outside the repository. A dataDir property is only written to .esedre/esedre.json if dataDir is a subdirectory within the project's repository (such as a monorepo subfolder or in-repo ticket directory), or if explicitly specified via --data-dir.
• Local In-Repo Overrides: If a repository explicitly specifies dataDir in its .esedre/esedre.json, the local configuration takes full precedence, ensuring standalone in-repo ticket stores remain completely independent.

Unique Project Codes Across Data Hubs

Project codes must be unique across all configured data hubs. Esedre does not support duplicate project codes across data hubs. If duplicate project codes are detected across multiple hubs:

• The storage engine loads only the first registered location.
• The CLI issues a warning notifying you of the collision (⚠️ Warning: Duplicate project code '<CODE>' detected across multiple data hubs...).
• Registering a new project that matches a code already present in another hub is rejected.

Case-Remembering Casing & Case-Insensitive Matching

Esedre follows a strict case-remembering but case-insensitive on matches design across all storage, CLI, MCP, and configuration layers:

• Case-Remembering Storage: Project codes preserve their original registered casing (e.g. Personal, Esedre, Prof) in directory names on disk (projects/Personal/) and in all metadata manifests (project.json, meta.json). Ticket metadata always records the canonical remembered casing. Re-registering or re-configuring a project preserves the existing remembered casing.
• Case-Insensitive Lookups & Access: All queries, CLI flags, MCP tool calls, ticket lookups (ese get personal-1, ese get PERSONAL-1, ese get Personal-1), and Agent Project Allow-List permissions (allowedProjects) match case-insensitively.
• Cross-Platform Filesystem Normalization: To prevent split directory fragmentation on case-sensitive filesystems (such as Linux ext4 or Docker), directory resolution matches existing parent directory entries case-insensitively, automatically reusing existing directory casing regardless of input variation.

🤖 Model Context Protocol (MCP) Setup

To connect Esedre to Google Antigravity, Claude Code, Cursor, or any MCP-compatible LLM agent:

{
  "mcpServers": {
    "esedre": {
      "command": "esedre",
      "args": ["mcp"]
    }
  }
}

Registered Tools

• esedre_list_tickets: List tickets with optional project, status, type, priority, milestone, isBlocked, linkedTo, search, or includePlan filter.
• esedre_get_ticket: Retrieve full specification, summary, comments, revision, links, blocker status, and content hash (sha1).
• esedre_get_plan & esedre_save_plan: Inspect and update implementation plans with optimistic concurrency (lastHash).
• esedre_create_ticket: Mint new roadmap tickets with project code validation (up to 8 chars), optional priority, optional milestone, and specification detail markdown.
• esedre_update_ticket: Modify status, title, type, priority, milestone, complexity, or effort with optimistic concurrency (lastHash).
• esedre_link_ticket: Establish a bi-directional link between two tickets (relates-to, blocks, parent-of, duplicates).
• esedre_unlink_ticket: Remove a bi-directional relationship between two tickets.
• esedre_list_milestones: List milestones and progress metrics for a project.
• esedre_get_milestone: Retrieve milestone specifications, umbrella feature flag, and member tickets.
• esedre_create_milestone: Create a project milestone with optional umbrella feature flag and target date.
• esedre_update_milestone: Update milestone status, title, description, or umbrella feature flag.
• esedre_add_comment: Append developer or LLM agent verification notes with optional file path or inline text.

Cross-Project Linked Issues & Dependencies

Esedre supports bi-directional ticket relationships across tickets within the same project or across different projects:

• Semantic Relations:
  • relates-to <-> relates-to (symmetric)
  • blocks <-> blocked-by (inverse)
  • parent-of <-> child-of (inverse)
  • duplicates <-> duplicated-by (inverse)
• Automatic Reciprocal Linking: Creating a link on Ticket A automatically establishes the reciprocal inverse relationship on Ticket B when both are in writable storage scope. Unlinking either removes both sides.
• Blocker Tracking & Dependency Awareness: Tickets with uncompleted blocked-by links are computed as isBlocked: true. The CLI highlights blocked items with [BLOCKED] warning badges, and LLM agents can query ready work via ese list --blocked or isBlocked: false in MCP.
• Cycle Prevention: Cycle detection on blocks and parent-of chains rejects circular dependencies that would deadlock workflows.
• Agent Allow-List Redaction: Links to external projects outside the active workspace's allowedProjects have target metadata redacted to [Restricted Project] to prevent cross-workspace information leakage.

Project Milestones & Umbrella Feature Flags

Esedre introduces first-class milestone management to group related tickets toward target deliverables and release cycles:

• Target Deliverables: Organize tickets under sequential project milestones (e.g. #1 Lab 151 Platform Foundation, #2 Public Release).
• Cross-Project Milestone Deliverables: Milestones can group member tickets across multiple projects (e.g. platform, web, and tooling repositories) toward a unified delivery target.
• Compound Milestone Notation: In multi-project or portfolio context, milestones are addressed and filtered using compound notation (ProjectCode:MilestoneTitle or ProjectCode:MilestoneId).
• Umbrella Feature Flag Inheritance: Milestones can optionally link to an umbrella feature flag, which automatically propagates to all tickets in the milestone unless individually overridden.
• Embed & Allow-List Isolation: When viewed from embedded host applications or scoped agent environments, tickets belonging to external projects outside allowedProjects render as masked placeholders, preserving project security boundaries.
• Visual Progress Tracking: Real-time progress bars, completion metrics, and assigned ticket chips in the Web UI dashboard.
• Full CLI & MCP Parity: Manage milestones from the terminal via ese milestone list, ese milestone create, and ese milestone update, or let autonomous LLM coding agents inspect deliverables via MCP tools (esedre_list_milestones, esedre_get_milestone).

Resources

• URI Scheme: esedre://tickets/{id} (MIME type: text/markdown)

🎨 Embeddable Component & Theming

Esedre includes a drop-in Web Component (<esedre-planner>) that allows you to embed the visual developer planner directly into any host web application (React, Vue, Svelte, or vanilla HTML) without adding UI framework dependencies to your project.

Component Usage

<!-- Load the Esedre embed script -->
<script type="module" src="node_modules/esedre/dist/web/embed.js"></script>

<!-- Embed the planner -->
<esedre-planner
  project="MYAPP"
  api-url="/esedre"
  show-header="false">
</esedre-planner>

Component Attributes

| Attribute | Default | Description | |---|---|---| | project | "all" | Filter tickets to a specific project code (e.g. Profe, Alce) or "all" | | api-url | "/api/planning" | Base URL of the Esedre server or reverse proxy endpoint | | show-header | "true" | Set to "false" to hide the top navigation header for seamless dialog/drawer embedding | | read-only | "false" | Disable ticket creation, editing, and plan modification |

Theming with CSS Tokens

The planner UI is styled entirely using CSS custom properties. When embedding inside host applications, you can override these tokens to match your app's visual identity:

:root {
  /* Surfaces & Backgrounds */
  --bg-main: #060812;              /* Main canvas background */
  --bg-card: #0b0f19;              /* Card containers */
  --bg-surface: #0a0e1a;           /* Surface panels */
  --bg-surface-elevated: #0f172a;  /* Headers & elevated panels */

  /* Borders & Accents */
  --border-subtle: #1e293b;        /* Subtle divider borders */
  --border-strong: #334155;        /* Interactive/hover borders */
  --accent-primary: #818cf8;       /* Primary interactive accent */

  /* Typography */
  --text-primary: #f8fafc;         /* High-contrast headings and titles */
  --text-secondary: #94a3b8;       /* Body and secondary text */
  --text-muted: #64748b;           /* Metadata and subtle labels */
}

• Standalone Theme Toggle: When running via ese start, users can toggle between Day (Light) and Night (Dark) themes with one click in the header. Theme preferences persist automatically in localStorage.

🛡️ Multi-Project Agent Isolation & Upward Discovery

Esedre enforces clean project isolation so each LLM agent is informed only of the projects it is authorized to access:

• Upward Discovery: When invoked in any subdirectory, Esedre climbs upward until it encounters the nearest .esedre/esedre.json or esedre.json, binding its execution to that repository's scope.
• Scoped Project Awareness: Storage operations and tools only inform and expose projects declared in allowedProjects. LLM agents cannot query, list, or mutate tickets outside their authorized scope.
• Unauthorized requests throw EsedreAuthorizationError:
  • CLI: Prints Access Denied: ... and exits with status code 1.
  • MCP: Responds with standard JSON-RPC error -32603.
  • REST API: Responds with HTTP status code 403 Forbidden.

🛠️ Development & Testing

# Run full unit and integration test suite
npm test

# Lint TypeScript types
npm run lint

# Build bundled standalone distribution & web components
npm run build

📄 License & Changelog

• License: Mozilla Public License 2.0 (MPL-2.0) © ARWAM
• Changelog: See CHANGELOG.md for detailed release notes and version history.