claude-code - 💡(How to fix) Fix [FEATURE] Allow project-local task list directory [1 participants]

Preflight Checklist

• I have searched existing requests and this feature hasn't been requested yet
• This is a single feature request (not multiple features)

Problem Statement

Claude Code's task list (the Ctrl+T view) persists to disk under ~/.claude/tasks/, optionally scoped to a named subdirectory via CLAUDE_CODE_TASK_LIST_ID. This is great for cross-session persistence, but the files always live in the global home directory.

There is no way to store a project's task list inside the project repo. This creates friction when:

• Switching machines: tasks for a project don't travel with the codebase, only with the home directory.
• Working in plan mode: an approved plan produces concrete next steps, but they live in a global location disconnected from the branch/PR they belong to.
• Coordinating with teammates or future-me across worktrees: there's no way to commit task state alongside the code it describes.

The current choices are: (a) global persistence, which mixes project state with everything else and doesn't follow the repo, or (b) an external issue tracker like beads, which is much heavier than the native task list and doesn't integrate with Ctrl+T, plan mode, or compaction-survival.

There's a gap between "ephemeral global todos" and "full external issue tracker" namely, "todos that live in the repo."

Proposed Solution

Add a configuration option that points the task list at an arbitrary directory, overriding the default ~/.claude/tasks/<id>/ location. Two reasonable shapes:

1. Env var: CLAUDE_CODE_TASK_LIST_DIR=.claude/tasks (mirrors the existing CLAUDE_CODE_TASK_LIST_ID pattern).
2. Settings field: "taskListDir": ".claude/tasks" in .claude/settings.json so it is committed with the repo and auto-applies for everyone working in it.

Relative paths would resolve against the project root (the directory Claude is launched from, or wherever .claude/settings.json lives). When set, all task-list reads and writes use that directory instead of ~/.claude/tasks/<id>/.

Behavior is otherwise unchanged: Ctrl+T toggles the view, tasks survive compaction, "show me all tasks" / "clear all tasks" work the same way.

Alternative Solutions

• CLAUDE_CODE_TASK_LIST_ID set to project name: works for "this project always uses its own bucket," but the files are still in ~/.claude/tasks/<id>/, so they don't follow the repo across machines and aren't visible in git status.
• Beads / external tracker: solves persistence-in-repo but is significantly heavier, requires creating issues before writing code, and doesn't integrate with the native task list UI or plan-mode flow.
• Symlink ~/.claude/tasks/<id>/ into the repo: technically works but is fragile, per-machine, and not discoverable to teammates.
• CLAUDE.md instruction telling Claude to mirror tasks to a project file: relies on model discipline, not enforcement.

Priority

Medium - Would be very helpful

Feature Category

Configuration and settings

Use Case Example

1. I'm working on a multi-step refactor on a feature branch in a repo.
2. I use plan mode to align on the approach. The plan has 6 concrete steps.
3. Claude creates a task list with those steps. With taskListDir: ".claude/tasks" in .claude/settings.json, the list is written to <repo>/.claude/tasks/.
4. I commit the task state alongside the code on the branch.
5. I switch to a different machine, pull the branch, launch Claude in the repo and the task list is already populated with where I left off, and Ctrl+T shows the same in-progress / pending state.
6. When the branch merges, the task file goes with it (or gets cleaned up via gitignore, my choice).

This makes the native task list a first-class part of branch-scoped work, the same way commits and PR descriptions are.

Additional Context

• The existing CLAUDE_CODE_TASK_LIST_ID env var (documented at https://code.claude.com/docs/en/interactive-mode#task-list) shows the team already considers task-list location configurable in principle. This request extends that mechanism from "named bucket" to "arbitrary directory."
• This would let .claude/settings.json be the single source of truth for project-scoped Claude Code behavior, alongside hooks, permissions, and env vars already configurable there.
• No change to default behavior: if the setting is unset, everything works exactly as it does today.