nixpkgs/docs/packages/td.md

# td

Minimalist CLI for tracking tasks across AI coding sessions.

## Description

td (task daemon) is a lightweight command-line tool designed for tracking tasks during AI-assisted coding sessions. It provides a simple, fast way to manage todos and maintain context across conversations with AI coding agents.

## Features

- ✅ **Minimal Task Tracking**: Simple, focused task management
- 🤖 **AI Session Aware**: Designed to work with AI coding workflows
- 📊 **Usage Tracking**: Track session usage and context
- 🔄 **Session Continuity**: Resume tasks from previous sessions
- 📝 **Git Integration**: Works alongside git workflows
- ⚡ **Fast**: Lightweight Go binary with minimal overhead

## Installation

### Via Overlay

```nix
{pkgs, ...}: {
  environment.systemPackages = with pkgs; [
    td
  ];
}
```

### Direct Reference

```nix
{pkgs, ...}: {
  environment.systemPackages = with pkgs; [
    inputs.m3ta-nixpkgs.packages.${pkgs.system}.td
  ];
}
```

### Run Directly

```bash
nix run git+https://code.m3ta.dev/m3tam3re/nixpkgs#td
```

## Usage

### Starting a Session

```bash
# Start a new session and view current tasks
td usage --new-session

# Quick view of current tasks (no session tracking)
td usage -q
```

### Basic Commands

```bash
# Show version
td version

# View help
td --help
```

### Task Management

td integrates with AI coding workflows to track tasks across sessions. Use it at the start of conversations to establish context:

```bash
# At conversation start (or after /clear)
td usage --new-session

# For subsequent reads within the same session
td usage -q
```

## Integration with AI Agents

td is designed to be used by AI coding agents as part of their workflow:

1. **Session Start**: Agent reads current tasks with `td usage --new-session`
2. **Work Progress**: Tasks are tracked and updated during the session
3. **Session End**: State is preserved for the next session

### Example Integration

In an AI agent's system prompt or configuration:

```
You must run td usage --new-session at conversation start (or after /clear) to see current work.
Use td usage -q for subsequent reads.
```

## Configuration

### Environment Variables

- `TD_DATA_DIR`: Custom directory for td data storage

### Data Storage

Task data is stored locally in the project or user directory. See upstream documentation for exact storage location.

## Build Information

- **Version**: 0.34.0
- **Language**: Go
- **License**: MIT
- **Source**: [GitHub](https://github.com/marcus/td)

## Platform Support

- Linux
- macOS (Unix systems)

## Notes

- Tests are disabled in the Nix package build due to git worktree operations
- Version check is enabled for the Nix package (`td version`)
- Minimal dependencies - pure Go binary

## Related

- [sidecar](./sidecar.md) - Uses td for integrated task management
- [opencode](./opencode.md) - AI coding agent that integrates with td
- [Adding Packages](../guides/adding-packages.md) - How to add new packages
- [Quick Start](../QUICKSTART.md) - Getting started guide