Working with AI

The CLI has a dedicated mode for AI agents. Add --ai to any command and the output changes from pretty terminal formatting to structured Markdown that LLMs can parse easily. This page explains how AI mode works and how to get the most out of it.

Why AI Mode Exists

AI agents and humans have different needs:

Human Needs	AI Agent Needs
Colors, alignment, visual appeal	Structured, parseable data
Fuzzy search (“the login task”)	Exact identifiers (file paths)
Interactive prompts for disambiguation	Single-call operations, no prompts
Readable summaries	Token-efficient output

Rather than compromise, the CLI provides distinct modes optimized for each. An AI agent can query your tasks, understand projects, and make changes—all through the same CLI you use, just with --ai appended.

The —ai Flag

Add --ai to any command to switch to AI mode:

tdn list --ai
tdn show "Review quarterly report" --ai
tdn context project "Q1 Planning" --ai

AI mode changes several things:

Output format — Structured Markdown instead of formatted terminal output
No prompts — Commands succeed or fail with a clear error; no interactive disambiguation
Paths included — Every entity includes its file path, so agents can make follow-up calls
Token-efficient — Compact notation where possible, progressive disclosure of detail

Output Format

AI mode outputs structured Markdown that LLMs can read directly. Here’s what tdn list --status ready --ai might return:

## Tasks (3)

### Review quarterly report

- **path:** /Users/you/notes/tasks/review-quarterly-report.md
- **status:** ready
- **created-at:** 2025-01-10
- **updated-at:** 2025-01-14
- **due:** 2025-01-15
- **project:** Q1 Planning

### Update documentation

- **path:** /Users/you/notes/tasks/update-documentation.md
- **status:** ready
- **created-at:** 2025-01-12
- **updated-at:** 2025-01-12

### Fix login bug

- **path:** /Users/you/notes/tasks/fix-login-bug.md
- **status:** ready
- **created-at:** 2025-01-08
- **updated-at:** 2025-01-14
- **project:** Q1 Planning

Each entity appears as a heading with consistent field formatting. The path is always first—agents need it for follow-up commands.

Why Markdown?

AI agents receive CLI output in their context window. Markdown works better than JSON for this:

Token-efficient — More compact than JSON or YAML
Degrades gracefully — If output is truncated (e.g., via head -100), partial Markdown is still useful; truncated JSON breaks
No parsing needed — LLMs read Markdown directly without code execution
Familiar format — LLMs are trained extensively on Markdown

The context Command

The context command is designed specifically for AI agents. It returns not just an entity, but everything around it—parent relationships, child entities, timelines, and excerpts.

Why context Matters

Without context, an agent helping with project planning would need multiple calls:

Get the project details
Get all tasks in the project
Get the parent area
Figure out what’s overdue, due today, etc.

The context command does all of this in one call:

tdn context project "Q1 Planning" --ai

Returns the project, its parent area (with excerpt), a timeline of due/scheduled tasks, and all active tasks grouped by status.

Vault Overview

Run context with no arguments for an orientation to the entire vault:

tdn context --ai

Here’s an abbreviated example of the output:

# Overview

**Stats:** 3 areas · 8 active projects · 34 active tasks · ⚠️ 2 overdue · 📅 3 due today · ▶️ 5 in-progress
_Excludes: done/dropped/icebox tasks, done projects, archived areas_

---

## Structure

### 📁 Work

Tasks: 18 total (4 direct, 14 via projects)
├── 🔵 Q1 Planning [in-progress] — 8 tasks (2▶️ 4🟢 1📥 1🚫)
│   ├── ▶️ Fix authentication bug
│   └── ▶️ Document API v2 endpoints
├── 🟢 Client Onboarding [ready] — 4 tasks (4🟢)
├── 🟡 Q2 Roadmap [planning] — 2 tasks (2📥)
└── 📋 Direct: 4 tasks (1▶️ 2🟢 1📥)
    └── ▶️ Review team capacity

### 📁 Personal

Tasks: 12 total (3 direct, 9 via projects)
├── 🔵 Home Renovation [in-progress] — 6 tasks (1▶️ 3🟢 2📥)
│   └── ▶️ Get contractor quotes
└── 📋 Direct: 3 tasks (1▶️ 2🟢)

---

## Timeline

### Overdue (2)

- **Fix critical security issue** — due Jan 10 — Q1 Planning → Work
- **Submit expense report** — due Jan 12 — Work (direct)

### Due Today (3)

- **Review PR #847** — Q1 Planning → Work
- **Call insurance company** — Personal (direct)

### Scheduled This Week

**Tomorrow (Thu Jan 16)**
- Team standup prep — Work (direct)

---

## In-Progress Tasks (5)

### Fix authentication bug

Q1 Planning → Work · due 2025-01-18

The SSO authentication flow is failing for enterprise users...

---

## Reference

| Entity       | Type    | Path                    |
| ------------ | ------- | ----------------------- |
| Work         | area    | areas/work.md           |
| Q1 Planning  | project | projects/q1-planning.md |
| Fix auth bug | task    | tasks/fix-auth-bug.md   |

Understanding the Format

The output follows a principle of progressive disclosure—most important information first, details later. An agent can stop reading at any point and still have useful context:

Stats — Quick counts and alerts (overdue, due today)
Structure — Visual hierarchy of areas, projects, and what you’re working on
Timeline — Time-sensitive items requiring attention
In-Progress Tasks — Full body content for active work
Excerpts — Project and area context (truncated to ~200 words)
Reference — File paths for follow-up commands

Emoji Notation

The structure tree uses emoji to convey status at a glance:

Project status:

🔵 in-progress
🟢 ready
🟡 planning
🚫 blocked
⏸️ paused

Task counts use a compact shorthand: (2▶️ 4🟢 1📥) means 2 in-progress, 4 ready, 1 inbox. Only non-zero counts appear.

Other indicators:

📁 marks an area
📋 marks “direct” tasks (belonging to an area without a project)
⚠️ overdue count
📅 due today count

Why This Format?

This format is designed specifically for LLM context windows:

Token-efficient — Emoji and shorthand notation pack more information into fewer tokens than verbose text
Gracefully degradable — If output is truncated, earlier sections (stats, structure) remain intact and useful
Self-contained — The reference table at the end provides file paths, so an agent can act on any mentioned entity without additional queries

This is the best first call for an agent that needs to understand your current work situation.

Area Context

tdn context area "Work" --ai

Returns everything about an area:

Full area details and body content
All projects in this area, grouped by status
Timeline scoped to this area’s tasks
In-progress tasks with full details
Up to 10 ready tasks
Project excerpts

Project Context

tdn context project "Q1 Planning" --ai

Returns:

Full project details and body content
Parent area summary and excerpt
Timeline scoped to this project’s tasks
All active tasks grouped by status (in-progress tasks get full detail)

Task Context

tdn context task "Fix authentication bug" --ai

Returns:

Full task details and body content
Alert banner if overdue, due today, or newly actionable
Parent project (if any) with excerpt
Parent area (if any) with excerpt, noting whether the relationship is direct or via project

AI Mode for Write Commands

Write commands also support --ai. The key difference: AI agents must use exact file paths for write operations.

Query First, Then Act

The pattern for AI agents is:

Query — Use list, show, or context to find entities and get their paths
Act — Use the returned paths for set status, update, archive, etc.

For example, an agent helping mark tasks done would:

# Step 1: Find the task
tdn list --query "quarterly report" --ai

# Step 2: Mark it done using the path
tdn set status /Users/you/notes/tasks/review-quarterly-report.md done --ai

This two-step pattern prevents mistakes. An agent can’t accidentally complete the wrong task because it must use an exact path, not a fuzzy title match.

Why Paths for Writes?

Fuzzy matching is convenient for humans but dangerous for agents. If an agent wants to mark “Fix bug” done and there are three tasks with “bug” in the title, which one should be affected?

By requiring exact paths for write operations, the CLI eliminates this ambiguity. The agent gets the path from a query, then uses that path for the action. No guessing.

Output Format Details

AI mode output follows consistent patterns that agents can rely on.

Entity Lists

## Tasks (3)

### Entity Title

- **path:** /absolute/path/to/file.md
- **status:** ready
- **created-at:** 2025-01-10
- **updated-at:** 2025-01-14
- **optional-field:** value

Required fields always appear (path, status, timestamps for tasks). Optional fields appear only when set.

Mutations

When a write command succeeds, output shows what changed:

## Task Updated

### Review quarterly report

- **path:** /Users/you/notes/tasks/review-quarterly-report.md

### Changes

- **status:** ready → done
- **completed-at:** (unset) → 2025-01-15

This confirms the change and shows before/after values.

Errors

Errors in AI mode are structured and include machine-readable codes:

## Error

- **code:** AMBIGUOUS
- **message:** Multiple tasks match "bug"
- **matches:**
  - Fix login bug (tasks/fix-login-bug.md)
  - Debug authentication (tasks/debug-auth.md)
  - Bug triage process (tasks/bug-triage.md)

The error code lets agents handle specific situations programmatically.

Combining —ai and —json

For agents that need both structured metadata and the full context output:

tdn context project "Q1 Planning" --ai --json

This wraps the AI Markdown in a JSON envelope:

{
  "contextType": "project",
  "entity": "Q1 Planning",
  "summary": "Context for project 'Q1 Planning': 8 active tasks",
  "content": "# Project: Q1 Planning\n\n**Stats:** 8 active tasks...",
  "references": [
    { "name": "Q1 Planning", "type": "project", "path": "projects/q1-planning.md" },
    { "name": "Work", "type": "area", "path": "areas/work.md" }
  ]
}

The content field contains the full AI Markdown. The references array provides structured access to entity paths without parsing the Markdown.

Best Practices for AI Integration

Orient First

When an agent starts helping with tasks, it should first understand the situation:

tdn context --ai

This single call tells the agent what areas and projects exist, what’s overdue, what’s in progress, and what’s coming up.

Use context Over Multiple list Calls

Instead of:

tdn list --project "Q1 Planning" --ai
tdn show "Q1 Planning" --ai
tdn list areas --ai

Use:

tdn context project "Q1 Planning" --ai

One call, complete picture.

Always Include —ai

Agents should always use --ai. Without it:

Output may contain ANSI color codes
Interactive prompts might hang waiting for input
Paths aren’t guaranteed to be included

Handle Errors Gracefully

Check for error codes in the output. Common ones include NOT_FOUND (entity doesn’t exist), AMBIGUOUS (multiple matches—use a more specific query or exact path), and PARSE_ERROR (file couldn’t be parsed—run tdn doctor --ai for details).

See the CLI Reference for the full list of error codes.

Claude Code Plugin Use the dedicated Claude Code plugin for even deeper AI integration