FAQ

Quick answers to common questions about taskmd.

Installation & Setup

How do I install taskmd?

The easiest way is via Homebrew:

brew tap driangle/tap && brew install taskmd

Alternatively, download pre-built binaries from the releases page, install with Go (go install github.com/driangle/taskmd/apps/cli/cmd/taskmd@latest), or build from source. Note that go install gives you the CLI only — the web dashboard is not included; use a pre-built binary, Homebrew, or Docker for that.

What are the system requirements?

Pre-built binaries work on macOS, Linux, and Windows with no additional dependencies. Building from source requires Go 1.25+. The web interface works in any modern browser.

How do I verify my installation?

Run taskmd --version to see version information. Run taskmd --help to see available commands.

How do I set up agent configuration files?

Agent configuration files are generated by taskmd init. Pass --claude, --codex, or --gemini (any combination) to choose which assistants to set up. These files help AI assistants understand your taskmd workflow.

It is safe to re-run init in an existing project to add an agent: files that already exist are skipped with a warning unless you pass --force.

Task Format

What is the task file format?

Tasks are markdown files with YAML frontmatter. The frontmatter contains structured metadata (id, title, status, etc.) enclosed in --- delimiters, followed by a markdown body for descriptions. See the Task Specification for complete details.

What frontmatter fields are required?

Only id (unique identifier) and title (brief description) are required. status is recommended. All other fields are optional.

How do I create my first task?

Create a file like tasks/001-my-first-task.md:

---
id: "001"
title: "My first task"
status: pending
---

# My First Task

Description of what needs to be done.

Then run taskmd list tasks/ to see your task. See the Quick Start for a full walkthrough.

What are valid status values?

pending (not started), in-progress (actively working), completed (finished), blocked (cannot proceed), and cancelled (will not be completed).

What's the difference between effort and priority?

Priority indicates importance (how critical the task is). Effort indicates complexity and time. A task can be high priority but small effort (urgent bug fix), or low priority but large effort (nice-to-have feature).

CLI Usage

How do I list all tasks?

taskmd list tasks/

Use --format json or --format yaml for machine-readable output.

How do I filter tasks?

# By status
taskmd list --filter status=pending

# By priority
taskmd list --filter priority=high

# Multiple filters (AND logic)
taskmd list --filter status=pending --filter priority=high

How do I find the next task to work on?

taskmd next tasks/

It lists actionable tasks (pending, with every dependency completed), ranked by priority, critical path, how many tasks each unblocks, effort, and phase order. Add --explain to see the score.

How do I visualize dependencies?

# Text-based graph
taskmd graph tasks/ --format ascii

# Mermaid diagram
taskmd graph tasks/ --format mermaid

The web interface also provides an interactive graph view.

Web UI

How do I start the web interface?

taskmd web start --task-dir tasks/ --open

Does the web UI auto-refresh?

Yes. It watches for file changes and updates automatically via Server-Sent Events.

What port does the web server use?

Default is 8080. Change it with --port: taskmd web start --port 3000.

Why can't I reach the dashboard from another machine?

By design: taskmd web start binds 127.0.0.1, so it only accepts connections from the machine running it. Bind every interface with taskmd web start --host 0.0.0.0, or set web.host in .taskmd.yaml.

Do this deliberately. The API is unauthenticated and, unless you pass --readonly, PUT /api/tasks/{id} rewrites task files on disk — so a wider bind hands task read/write access to anything that can reach the address. Pair it with --readonly and a firewall or VPN on untrusted networks.

Can I use the web UI in production?

The web UI is designed for local development and personal use. It has no authentication and lacks the security features needed for internet-facing deployments. While it's suitable for small teams on trusted networks, treat it as a development tool rather than a production application.

Dependencies

How do I add task dependencies?

Add a dependencies array to the frontmatter:

dependencies:
  - "001"
  - "015"

Dependencies indicate which tasks must be completed before this one can start.

What happens with circular dependencies?

The validate command detects circular dependencies and reports an error. Resolve by restructuring your tasks to break the cycle.

How do dependencies affect task recommendations?

The next command only suggests tasks whose dependencies are all completed. It also prioritizes tasks that unblock the most other work.

Configuration

Can I set default options?

Yes. Create a .taskmd.yaml file in your project root or home directory. See Configuration for details.

Where should I put my config file?

• Project-level: .taskmd.yaml in your project root (takes precedence)
• Global: ~/.taskmd.yaml for user-wide defaults

What can I configure?

dir: ./tasks                    # Default task directory
web:
  port: 8080                   # Web server port
  auto_open_browser: true      # Auto-open browser

Troubleshooting

Why won't my task file parse?

Common issues: missing --- delimiters, invalid YAML syntax, incorrect indentation, or missing required fields. Run taskmd validate tasks/ to see specific errors.

Why is my task not showing up?

Check that: the file ends with .md, frontmatter has valid YAML, required fields (id, title) are present, and you're scanning the correct directory.

Why is the graph command failing?

Usually caused by circular dependencies or missing task references. Run taskmd validate tasks/ first to identify issues.

Best Practices

How should I organize task files?

For small projects (< 50 tasks), a flat tasks/ directory works well. For larger projects, use subdirectories by feature area (tasks/cli/, tasks/web/). Use NNN-descriptive-title.md naming.

How granular should tasks be?

Aim for tasks completable in hours to a few days. Use subtasks (markdown checkboxes) for finer-grained tracking within a task. Create separate tasks when items need individual dependencies or tracking.

Should I delete completed tasks?

Keep them for historical reference. Use --exclude-status completed to hide them from views, or move them to an archive/ subdirectory.

Can I use taskmd in a monorepo?

Yes. Each project can have its own tasks/ directory, or you can keep a shared tasks directory at the root and organize by subdirectory (tasks/frontend/, tasks/backend/). The group field also helps categorize tasks logically across projects.

Need More Help?

• Quick Start - Hands-on tutorial
• CLI Guide - Full command reference
• Task Specification - Complete format details
• GitHub Issues - Report bugs or request features