Claude Code tasks: project-level and persistent across sessions

claude_tasks_project.md

Claude Code Persistent Task Lists

This guide explains how to set up task lists that persist across Claude Code sessions for a specific project.

How It Works

Claude Code's task system stores tasks in ~/.claude/tasks/<task-list-id>/. By default, each session gets a random UUID. To persist tasks across sessions, you set the CLAUDE_CODE_TASK_LIST_ID environment variable to a consistent ID for your project.

One-Time Setup (Already Done)

1. Install direnv:

   brew install direnv

2. Add direnv hook to your shell (add to ~/.zshrc):

   eval "$(direnv hook zsh)"

3. Restart your terminal or run source ~/.zshrc

Per-Project Setup

Step 1: Create the .envrc file

In your project root, create a .envrc file:

export CLAUDE_CODE_TASK_LIST_ID=your-project-slug

Use a descriptive slug like pe-value-creation-s2026, startup-app, etc.

Step 2: Create the task directory

mkdir -p ~/.claude/tasks/your-project-slug

Use the same slug as in your .envrc file.

Step 3: Allow direnv

From the project directory:

direnv allow

Step 4: Start Claude Code

Start a new Claude Code session in the project directory. The environment variable will be automatically set.

Step 5: Create initial tasks

Ask Claude to create tasks for your project. Example prompts:

• "Let's create a task list for this project"
• "Create tasks for [describe your goals]"
• "Add a task to [specific task]"

Managing Tasks

View tasks

• Ask: "What are my tasks?" or "Show the task list"
• Claude will use the TaskList tool

Update task status

• "Mark task 3 as complete"
• "Start working on task 5" (sets to in_progress)

Add new tasks

• "Add a task to review the syllabus"
• Claude will use TaskCreate

Migrating Existing Tasks to a New Project

If you created tasks in a session before setting up persistence, ask Claude:

"Copy the current session's tasks to ~/.claude/tasks/your-project-slug/"

Then set up the .envrc as described above.

Troubleshooting

Tasks not persisting

1. Verify the env var is set: echo $CLAUDE_CODE_TASK_LIST_ID
2. Make sure you ran direnv allow
3. Restart Claude Code (not just the terminal)

direnv not loading

• Check that the hook is in your .zshrc
• Run source ~/.zshrc
• Verify with direnv status

View task files directly

ls ~/.claude/tasks/$CLAUDE_CODE_TASK_LIST_ID/
cat ~/.claude/tasks/$CLAUDE_CODE_TASK_LIST_ID/1.json

Notes

• Task IDs are simple integers (1, 2, 3...)
• Each task is stored as a separate JSON file
• Tasks support dependencies via blocks and blockedBy fields
• The task system is session-aware but file-based for persistence