{"id":30717946,"url":"https://github.com/langadventurellc/task-trellis-mcp","last_synced_at":"2026-08-27T15:56:32.628Z","repository":{"id":308086417,"uuid":"1031545540","full_name":"langadventurellc/task-trellis-mcp","owner":"langadventurellc","description":"Greatly improve how AI coding agents handle complex projects. Task Trellis helps track requirements for projects, breaks them down into smaller manageable parts until you have trackable and assignable tasks with built-in workflow management, dependency handling, and progress tracking. Basically, it's like Jira for coding agents.","archived":false,"fork":false,"pushed_at":"2026-04-26T04:26:01.000Z","size":909,"stargazers_count":6,"open_issues_count":0,"forks_count":7,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-26T06:23:43.116Z","etag":null,"topics":["ai-agents","claude-code","mcp","vibe-coding"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/@langadventurellc/task-trellis-mcp","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/langadventurellc.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-04T00:55:38.000Z","updated_at":"2026-04-26T04:25:41.000Z","dependencies_parsed_at":"2025-08-04T04:54:24.841Z","dependency_job_id":"0d24d18c-a4c3-4f4d-bd89-060c537f6aaf","html_url":"https://github.com/langadventurellc/task-trellis-mcp","commit_stats":null,"previous_names":["langadventurellc/task-trellis-mcp"],"tags_count":24,"template":false,"template_full_name":null,"purl":"pkg:github/langadventurellc/task-trellis-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/langadventurellc%2Ftask-trellis-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/langadventurellc%2Ftask-trellis-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/langadventurellc%2Ftask-trellis-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/langadventurellc%2Ftask-trellis-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/langadventurellc","download_url":"https://codeload.github.com/langadventurellc/task-trellis-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/langadventurellc%2Ftask-trellis-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":36944063,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-08-22T15:14:58.755Z","status":"online","status_checked_at":"2026-08-27T02:00:07.166Z","response_time":96,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","claude-code","mcp","vibe-coding"],"created_at":"2025-09-03T09:02:46.700Z","updated_at":"2026-08-27T15:56:32.623Z","avatar_url":"https://github.com/langadventurellc.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Task Trellis MCP\n\n**Project planning and task management built specifically for AI agents**\n\n[![npm version](https://badge.fury.io/js/%40langadventurellc%2Ftask-trellis-mcp.svg)](https://www.npmjs.com/package/@langadventurellc/task-trellis-mcp)\n[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)\n\nTask Trellis is an MCP server for project planning and task management built specifically for AI agents. It helps by breaking down complex projects and tracking their progress with built-in task management, complete with progress tracking, dependency management, and workflow automation. By default, all data is stored locally in Markdown files.\n\nPrimarily built as a much better alternative to managing markdown checklists. Task Trellis will make it easier to define requirements, specifications, and tasks in a structured way that the agents can actually use directly.\n\nFull documentation is available in the [docs](docs/index.md) folder.\n\n## Table of Contents\n\n- [At a Glance](#at-a-glance)\n- [Why Task Trellis?](#why-task-trellis)\n- [Core Benefits](#core-benefits)\n- [Usage](#usage)\n- [Installation and Configuration](#installation-and-configuration)\n- [Configuration](#configuration)\n- [Available Tools](#available-tools)\n- [Troubleshooting](#troubleshooting)\n\n## At a Glance\n\n| Prompt                                                                                                  | Result                                                                                                 |\n| ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |\n| /task-trellis:create-project (my project details)                                                       | _project created with epics, features and tasks defined and dependencies identified_                   |\n| Complete the next available task                                                                        | _next open task with dependencies satisfied is claimed and worked on_                                  |\n| Work on all of the tasks for feature F-my-feature                                                       | _all tasks for the specified feature are claimed and worked on_                                        |\n| Show me all open tasks in (my project)                                                                  | _list of all open tasks in the specified project_                                                      |\n| After working on (feature), there's a bug. Look at what changed and fix it.                             | _bug identified by examining all the files that were modified while working on that feature and fixed_ |\n| /task-trellis:create-features (feature details). Look at (other feature) and follow the same pattern    | _new feature created by mirroring the pattern of the other feature_                                    |\n| (after finding issue with design) Update all tasks in F-my-feature and update the design specifications | _all tasks in the specified feature are updated to reflect the new design specifications_              |\n\n## Why Task Trellis?\n\n### Without Task Trellis\n\n- AI agents lose track of complex, multi-step projects\n- Agents spin out of control with no clear task structure\n- Tasks are often too large or vague, leading to confusion\n- No way to manage dependencies or prerequisites\n- No visibility into what's been completed vs. what's pending\n- Tasks get forgotten, duplicated, or done out of order\n- Zero coordination between multiple AI sessions\n- Complex projects become chaotic and overwhelming\n\n### With Task Trellis\n\n- **Structured Breakdown**: Automatically organize projects into hierarchical tasks (depending on the size of the effort required)\n  - Project → Epic → Feature → Task\n  - See [Picking a Parent Issue Type](docs/issues.md#picking-a-parent-issue-type)\n- **Smart Dependencies**: Prevent tasks from starting until prerequisites are complete\n- **Progress Tracking**: Real-time visibility into what's done, in-progress, and pending\n- **Session Continuity**: Pick up exactly where you left off across AI conversations\n- **Workflow Management**: Built-in task claiming, completion, and validation workflows\n- **File Change Tracking**: Automatic documentation of what files were modified for each task\n- **Learn from History**: AI agents can reference past work to inform future tasks\n\n## Core Benefits\n\n**Focused Execution**: AI agents work on one clearly-defined task at a time  \n**Progress Visibility**: Always know project status and what's next  \n**Dependency Management**: Automatic task ordering based on prerequisites  \n**Audit Trail**: Complete history of all work completed and changes made  \n**Multi-Session Support**: Seamlessly collaborate across different AI conversations  \n**Productivity Boost**: Reduce context switching and eliminate forgotten tasks\n\n## Usage\n\nSee full documentation at [Task Trellis MCP Documentation](docs/index.md)\n\n### Basic Workflow\n\n1. **Create Tasks**\n   - Determine your starting point based on the expected size of your project\n     - **Project** - For sprawling initiatives with many moving parts\n     - **Epic** - For large feature groupings\n     - **Feature** - For specific functionality\n     - **Task** - For individual work items\n\n2. **Claim \u0026 Work on Tasks**\n   - AI agent claims next available task\n     - Excludes tasks that have incomplete prerequisites\n     - Grabs the next highest priority available task\n     - Mark a task as `draft` if you don't want it to be worked on yet - it won't be claimed when the tool looks for the next available task\n   - Works on the specific task requirements\n   - Marks task complete with file changes documented\n     - Automatically tracks which files were modified\n     - Logs summary of changes made\n     - Work done in the future could reference this to better understand the current state of the project\n\n3. **Track Progress**\n   - View completed vs. pending work\n   - See dependency relationships\n   - Monitor overall project health\n\n## Installation and Configuration\n\nSee [installation instructions](docs/installation.md).\n\n## Configuration\n\n### CLI Flags and Environment Variables\n\n| Flag / Env var         | Description                                               | Required |\n| ---------------------- | --------------------------------------------------------- | -------- |\n| `--projectDir \u003cpath\u003e`  | Override the project directory (default: `process.cwd()`) | No       |\n| `$TRELLIS_PROJECT_DIR` | Same as `--projectDir`; used when the flag is not passed  | No       |\n| `$TRELLIS_DATA_DIR`    | Override the shared data root (default: `~/.trellis`)     | No       |\n| `$TRELLIS_UI_PORT`     | Override the browser UI port (default: `3717`)            | No       |\n\nThe MCP server resolves the project directory in this order: `--projectDir` flag → `$TRELLIS_PROJECT_DIR` → current working directory. Since Claude Code launches MCP servers with the workspace as CWD, no flag is normally needed.\n\n### Shared Data Directory Layout\n\nData is stored in `~/.trellis/` (shared across all sessions), not inside the repo directory.\n\n```\n~/.trellis/\n  projects/\n    \u003c12-char-key\u003e/        ← sha1(gitOriginUrl or absolutePath).slice(0,12)\n      p/ e/ f/ t/         ← issues (unchanged internal layout)\n      meta.json           ← { \"label\": \"\u003cgitOriginUrl or absolutePath\u003e\" }\n```\n\n### Browser UI\n\nWhen the first Claude Code session starts the MCP server, it binds `http://127.0.0.1:3717` and logs:\n\n```\nTask Trellis UI: http://127.0.0.1:3717\n```\n\n- Subsequent sessions detect the port is taken and run STDIO-only.\n- The UI shows all projects under `~/.trellis/projects/` and supports creating, editing, and deleting issues directly in the browser.\n- When the leader session exits, the port is released automatically.\n\n#### Project Tree Navigation\n\nThe project tree view includes several features for navigating and filtering issues:\n\n- **Expand/Collapse**: Click the chevron next to an issue to expand or collapse its children. Open/closed state is automatically saved per project.\n- **Hide Completed**: Click the filter icon (top toolbar) to toggle hiding completed (done/wont-do) issues. This preference is saved per project.\n- **Search**: Use the search box to filter issues by title or content. Search results are displayed flat and ignore the hide-completed preference.\n- **Issue Details**: Click any issue row to view and edit its full details in the side panel.\n\n### Breaking Changes\n\n\u003e **Breaking change:** `--projectRootFolder` has been removed. Use `--projectDir` instead.\n\u003e\n\u003e **Breaking change:** The `activate` MCP tool has been removed. The project directory defaults to the current working directory; override with `--projectDir` or `$TRELLIS_PROJECT_DIR`.\n\u003e\n\u003e **Note:** Data previously stored in `\u003crepo\u003e/.trellis/` is not migrated automatically. Move or recreate your data under `~/.trellis/`.\n\n## Available Tools\n\n### Core Issue Management\n\n- **create_issue** - Create projects, epics, features, or tasks with hierarchical relationships\n- **update_issue** - Modify issue properties, status, priority, prerequisites, or labels\n- **get_issue** - Retrieve detailed issue information with history and relationships\n- **list_issues** - Query and filter issues by type, status, priority, or scope (returns issue summaries)\n- **delete_issue** - Remove issues (with dependency validation)\n- **replace_issue_body_regex** - Make targeted body content edits using regex patterns\n\n### Task Workflow Management\n\n- **claim_task** - Claim available tasks for execution with automatic priority ordering\n- **complete_task** - Mark tasks complete with file change documentation\n- **get_next_available_issue** - Use this tool to find the next available issue that's ready to work on.\n- **append_issue_log** - Add progress notes and status updates to task history (occurs automatically on task completion)\n- **append_modified_files** - Record files modified during task execution with change descriptions (occurs automatically on task completion)\n\n### Attachment Management\n\n- **add_attachment** - Copy a file into the managed attachments folder for an issue (errors if the issue or source file does not exist, or a file with the same name already exists)\n- **remove_attachment** - Delete a named file from an issue's attachments folder (errors if the issue or file does not exist)\n\nAttachments are returned as a list of filenames when calling **get_issue** and are linked in the browser UI detail view.\n\n### Project Files\n\n- **write_project_file** - Write a UTF-8 text file to the project's files directory. Overwrites by default; pass `failIfExists: true` to error on collision instead.\n- **read_project_file** - Read a UTF-8 text file from the project's files directory.\n- **list_project_files** - List filenames in the project's files directory (returns `[]` if the directory does not yet exist).\n- **delete_project_file** - Delete a named file from the project's files directory.\n\nProject files live at `~/.trellis/projects/\u003ckey\u003e/files/\u003cfilename\u003e` and are scoped to the project — not tied to any individual issue. Filenames must not contain path separators or `..` (path-traversal protection); v1 supports a flat namespace of UTF-8 text files.\n\n### Browser UI\n\n- **get_ui_info** - Returns the URL and port of the Task Trellis browser UI; use when the user asks about the UI or wants to view issues in a browser\n\n### System Management\n\n- **prune_closed** - Clean up old completed/cancelled issues for maintenance\n\n## Troubleshooting\n\n### Common Issues\n\n**Configuration issues:**\n\n- Validate JSON syntax in MCP client configuration\n- Ensure absolute paths are used for `--projectDir`\n- Restart your MCP client after configuration changes\n\n### Getting Help\n\n- **Issues**: [Report bugs or feature requests](https://github.com/langadventurellc/task-trellis-mcp/issues)\n- **Documentation**: Check this README and [docs](docs/index.md)\n\n## License\n\nGPL-3.0-only - see [LICENSE](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flangadventurellc%2Ftask-trellis-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flangadventurellc%2Ftask-trellis-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flangadventurellc%2Ftask-trellis-mcp/lists"}