Claude Code’s in-built JIRA

Claude Code just shipped a built-in task management system with dependency tracking. Yep, it’s basically JIRA! No, you don’t have to manage it yourself. Claude handles task creation, status updates, owners and blocking dependencies automatically.

But there’s a catch: This feature is in its infancy and currently by default, task lists are session-scoped. Start a new terminal, and your task list vanishes.
I spent some time figuring out how to make tasks persist across sessions and stay project-specific (so that tasks from one project don’t bleed into another).

Since mastering long-running agent harnesses and workflows, Anthropic’s Claude Code team has been shipping updates and features like Cristiano Ronaldo scored goals; relentlessly, and with an almost suspicious consistency.

With V2.1.19, Claude Code now supports a built-in stateful task management system with dependency tracking that replaces the earlier ToDoWrite / ToDoRead tools.

Here’s how the earlier system of ToDos worked:

• Session scoped by default
• No dependency tracking
• Limited visibility into task state
• No cross-session persistence without manual workarounds

While this isn’t much of an issue for smaller projects that can be coded up in a couple of days, for long-horizon projects this posed a significant challenge. It required the user orchestrating the development workflow with Claude to keep track all the tasks that were completed and the next tasks in line. There are a number of open-source solutions that address this orchestration such as Beads.

Claude’s new Task Management System

The new task-management system addresses the shortcoming of the ToDo system with:

• Persistent task lists – viewable to individual users, teams, and agents
• Dependency Management – using “blocks”/”blocked by”)
• Status Workflow – using “pending” → “in-progress” → “completed”
• Owner Assignment – for multi-agent orchestration
• Task Summary & Description – Summaries are visible to the user, descriptions are visible to Claude
• Cross-session visibility – Task lists persist across sessions and terminals and teams, if project scoped

Now, I know what you’re thinking. That sounds suspiciously familiar to that one tool all of us absolutely love to hate – what’s it called again – Oh, JIRA!. Only now, you don’t have to do any of that pesky management yourself. Claude will do that for you and you run the show.

However, there’s a catch. Once you understand the gotchas, you can work around them. Below, I explain how to leverage Claude’s task management system with some initial setup on your end. Keep in mind that task management is still in its early stages; these steps may not be needed in future versions.

The Plan & Execute Model

Before we move on setting up persistent task management within Claude Code, it is essential to understand the basic workflow of working with Claude Code model. Every user eventually figures out their own workflow, but abstracted, the common workflow to get the best out of Claude Code looks like this:

This workflow is beneficial because it provides separation of concerns.

Setting up Cross-Session Task Persistence

Because the task management system is new, there are some nuances to getting it to work reliably. It’s important to understand the different variables to consider, especially if you are working with multiple projects.

The Key: CLAUDE_CODE_TASK_LIST_ID

By default, Claude Code creates a unique task list per session (stored as a UUID). To make a task list persistent and avoid spawning a new one in every session, set the CLAUDE_CODE_TASK_LIST_ID environment variable before starting Claude Code.

# Tasks persist to ~/.claude/tasks/my-project
CLAUDE_CODE_TASK_LIST_ID = my-project claude

This ensures that every time you start Claude, it starts with the task list for that project. However, what happens when you are working on multiple projects?

Per-Project Configuration

The issue with the task list ID implementation is that if you set a global ID, all projects share one task list, which would be an unmitigated disaster. To avoid this, use a launcher script that auto-detects your project and sets the task list ID to that project.

I. Project-aware launcher script

I had Claude create and save this script with the filename: “claude-project”

#!/bin/bash
# ~/.local/bin/claude-project
detect_project() {
  case "$PWD" in
    */my-webapp*)        echo "my-webapp" ;;
    */data-pipeline*)    echo "data-pipeline" ;;
    */mobile-app*)       echo "mobile-app" ;;
    *)                   echo "" ;;
  esac
}
PROJECT_ID=$(detect_project)
if [[ -n "$PROJECT_ID" ]]; then
  echo "Task list: $PROJECT_ID"
  export CLAUDE_CODE_TASK_LIST_ID="$PROJECT_ID"
else
  echo "No project detected - using session-based tasks"
fi
exec claude "$@"

II. Installation

Once the file is created, it needs to be moved to the right location and made executable. Run the sequence of commands as outlined in your terminal. Step 4 is essential if you are a Windows user and using Powershell or WSL as your terminal.

# 1. Save script to PATH
mkdir -p ~/.local/bin
# 2. Copy the script to this folder
cp /<original path>/claude-project ~/.local/bin/
# 3. Make executable
chmod +x ~/.local/bin/claude-project
# 4. Fix Windows line endings (CRITICAL for WSL users as files created on Windows have CRLF endings that break bash scripts)
sed -i 's/\\r$//' ~/.local/bin/claude-project
# 5. Ensure PATH includes ~/.local/bin
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
# 6. Reload your shell
source ~/.bashrc

III. Usage

This is the most important project. Typically, you’d launch Claude from your project folder using a simple “claude” command, but going forward you need to use the command: “claude-project”.

# Navigate to project directory
cd ~/projects/my-webapp
# Launch with project-aware tasks
claude-project
# Output: "Task list: my-webapp"
# Tasks now persist to ~/.claude/tasks/my-webapp/

And you’re set! As you work with Claude Code using the workflow outlined earlier, Claude will generate the task list and this will persist across sessions. Here’s and example of a task list I created in a previous session that persisted into the new session and stayed until I exited out of it (note how it shows task #7 as blocked by preceding tasks). This task list will still be available to me in the next session, as long as I start Claude using my aliased command, “claude-project” instead of simply “claude”.

What’s Next?

Claude Code’s task management system is a major step forward, but it’s still in its infancy and I’d love for Anthropic to invest more into this awesome feature. Few enhancements that would help immensely:

Per-project scoping out of the box

Users shouldn’t need a launcher script to prevent task list collisions, and there should be an easier way to set per-project scoping. Claude Code already knows the present working directory; it should default to project-scoped task lists or provide users to manage these lists.

A Task List management layer

Currently, you can’t switch between task lists, archive completed ones, or even see what task lists exist without inspecting ~/.claude/tasks/ directly. A simple “/tasks list” and “/tasks switch” would go a long way.

While there is a /tasks command, I found that it doesn’t work reliably. Here’s a screenshot of the command telling me that there are no tasks currently running, which indicates that this command is meant to manage background tasks such as tool uses, agents and not the task list itself (the task list in the screenshot is always visible, unless I press ctrl+t to hide).

Dependency visualization

The “blocked by” relationships are powerful, but without a way to see the full dependency graph, you’re flying blind on complex projects. Even a text-based tree view would help.

Export/import for team workflows

If task lists persist across sessions, they should be shareable. A JSON export that integrates with Linear, JIRA, or even GitHub Issues would close the loop between Claude’s execution tracking and organizational project management.

These are solvable problems and I hope Anthropic has at least some of these on their, er, “task list” (meta reference, here). Until then, the launcher script approach should help you keep plodding on.

If you found this guide helpful, let me know!