
claude-timeline
Timeline mods for Claude Code
Install with your AI
Paste into Claude Code, Cursor, or any agent — it reads the repo and wires the tool into your project.
Install and set up claude-timeline (claude-plugin project) into my current project. Found on https://claudeers.com/claude-timeline Repo: https://github.com/skanehira/claude-timeline Homepage/docs: — Detected install method: claude-plugin → /plugin install claude-timeline@skanehira/claude-timeline Category: plugins. Platforms: cli, api. Read the repo's README for exact setup and env vars, then install it and wire it into my project. Claudeers Health Verdict: unknown; community-verified: false. Confirm the source before running anything.
⚠ Unverified / not recently updated — review before pasting a run-this config.
/plugin marketplace add skanehira/claude-timeline /plugin install claude-timeline@skanehira/claude-timeline
git clone https://github.com/skanehira/claude-timeline
// compatibility
| Platforms | cli, api |
|---|---|
| Operating systems | — |
| AI compatibility | claude |
| License | MIT |
| Pricing | open-source |
| Language | TypeScript |
claude-timeline
A Claude Code mod that keeps weighted task trees beside the chat. Claude plans each goal as a task tree, records progress as it goes, and writes short timed reports. You follow the progress in a one-row band above the prompt and in a side pane.
Use it
Install it at the prompt of a terminal session:
/plugin install timeline --marketplace skanehira/claude-timeline
Answer y to add the marketplace, then pick a scope. From a shell, the same is claude plugin install timeline --marketplace skanehira/claude-timeline.
To try a working copy instead, start Claude Code with it as a plugin folder:
claude --plugin-dir /path/to/claude-timeline
During a multi-step task Claude calls the timeline_tasks tool. Each top-level task is one task tree: its title names the goal, and its subtasks are the steps. A task can carry a description of what it will do, a note on what happened (its result, or why it is blocked), and, for a task without subtasks, its units of work as done: [completed, total]. Claude raises the completed count as each unit finishes, and raises the total when it finds more work. The band above the prompt then shows the progress of the tree the pane shows (see below), a bar split into completed (green), in progress (blue), blocked (red) and pending (gray) work, and the tree's task in progress without subtasks (the step being worked on, not its parent). On a narrow terminal the band drops the legend first and shortens the task title, so it stays one row. Before the first task tree, the band shows only Timeline and Open task tree, so the pane opens from the band at any time.
The labels follow Claude Code's language setting: Japanese when it names Japanese (for example "language": "Japanese"), English otherwise.
The pane
Type /timeline, or select Open task tree in the band (or Hide task tree while the pane is open), to toggle the pane. It has two tabs.
Task tree shows one tree at a time. ‹ and › move to the previous and next tree, and the line under the title reads its position, such as 2 / 2. The pane opens on the tree with a task in progress, else on the newest tree; once you move with ‹ ›, it keeps the tree you chose while that tree exists. The band shows the same tree.
- The progress card shows the tree's status chip, Request to continue, a bar, the completed share with two decimals, how many leaf tasks are completed (for example
0/8), and the time since the tree was added (<1m,5m,1h 5m,1d 2h;—when that time is unknown). - Request to continue sends Claude a prompt that asks it to continue the work on this tree.
- Each task row shows a status mark (
○not started,◐in progress,●completed,✕blocked), the title, a bar and the completed share, with a status chip below. - Comment history at the bottom lists the Discuss messages for the tree's tasks; select it to show or hide them.
Select a task row to replace the tree with the task's detail; ‹, or b, returns to the tree.
- The head shows the task's title and status chip, the title of its tree, and the task's description and note.
- Three cards show the task's completed share with two decimals, its weight, and its completed units: for a task without subtasks its
done(for example1 / 2;0 / 1or1 / 1without units), and for a task with subtasks how many of its leaf tasks are completed. - Comments lists the Discuss messages for the task with their date and time, or reads that there are none. Type in Discuss and press Enter to ask Claude about the task; the field reads
▶ Discusswhile it has the focus. The message is kept with the task. - History lists the task's revisions, newest first (a task with subtasks also gets one whenever a change to its subtasks moves its status or completed share, so its newest revision matches its chip), and is open at first; select it to hide or show them. Each revision shows its date and time (
2026/11/15 11:28:42; dashes when the time is unknown), the status after it, the task's completed share before and after it (0.00% → 100.00%), the task's weight, the description and note it set, and for a subagent's change the subagent id.
Reports lists the timed reports, newest first; the tab shows how many there are. /timeline report writes one now.
Each timeline_tasks call in the conversation gets a card under its row with the progress before and after the call and the tasks it changed.
Keyboard
| To | Press |
|---|---|
| Open the pane and give it the keyboard | /timeline while the pane is closed |
| Toggle the pane from the band | ctrl+x tab until Open task tree is selected, then t |
| Toggle the pane from the prompt | the chord you bind to app:toggleDiffPreSession, such as ctrl+x t |
| Give an open pane the keyboard | ctrl+x tab, repeated until the pane has it |
Move between the tabs, ‹ ›, Request to continue, task rows, Discuss and Comment history | tab / shift+tab |
Move between ‹, Discuss and History in a task's detail | tab / shift+tab |
| Return from a task's detail to the tree | b, or enter on ‹ |
| Show Task tree or Reports | 1 / 2 |
| Press the selected control, or open the selected task row's detail | enter |
| Send a Discuss message | type it, then enter |
| Give the keyboard back to the prompt | esc (the pane stays open; in a task's detail, esc does not return to the tree) |
| Close the pane | ctrl+x x while the pane has the keyboard |
ctrl+x tab visits the controls of every row in the band, other mods' rows included, before it reaches the panes, so the number of presses depends on what else is installed and on where the keyboard was. Claude Code does not hand the keyboard to a pane opened from the band, or to a pane that is already open when you type /timeline: after t, the keyboard is back at the prompt.
A mod cannot add a keybinding action of its own, so Open task tree answers the chord of Claude Code's app:toggleDiffPreSession action, which has no default key. To open the pane with ctrl+x t, add the binding to ~/.claude/keybindings.json:
{
"bindings": [
{
"context": "Chat",
"bindings": {
"ctrl+x t": "app:toggleDiffPreSession"
}
}
]
}
The chord works from the prompt while no dialog is up, and does nothing during a survey, when the band leaves its row to the survey. It opens the pane while it is closed and closes it while it is open.
How progress is counted
Weights compare tasks under the same parent. A completed task of weight 3 beside an unstarted task of weight 1 gives 75%. Subtasks divide their parent's share, so splitting a task into subtasks leaves its share unchanged.
A task without subtasks counts its completed units: done: [1, 2] counts half of its share as completed work, and the rest toward its status. A task of weight 1 at [1, 2], beside two completed tasks of weights 1 and 3, gives 90%, and the task's own row reads 50%. When Claude finds more work, it raises the total, so [1, 2] becomes [1, 3] and the task reads 33.33%. Without a status, the units set it: [0, 3] is not started, [1, 3] in progress, [3, 3] completed. Completing a task completes all its units, and a task not started cannot have completed units. A task without units counts 0 until it is completed.
A task with subtasks takes its status and progress from its subtasks; Claude sets status and units only on tasks without subtasks. It reads completed when every subtask is completed, in progress when a subtask is in progress, blocked when a subtask is blocked and none is in progress, in progress when some subtasks are completed and the rest not started, and not started otherwise. Work with anything left shows at most 99.99%, so 100% means every task under it is completed. The tree's status chip is its top-level task's status, so a row, its parent's row, the progress card and the band always agree.
A done that is not two numbers with 0 ≤ completed ≤ total and total > 0 is refused with an error, and the call leaves that task unchanged. A status or done sent to a task with subtasks is refused with an error, and the rest of that operation still applies. A weight must be a number above 0; any other weight is refused with an error, and the call leaves that task unchanged.
Options
Set these in /config (or under pluginConfigs.timeline.options in settings):
| Option | Default | Meaning |
|---|---|---|
reminderSteps | 8 (model requests) | Requests in one turn without a timeline_tasks update before Claude is reminded to record progress; with no task tree yet, Claude is reminded once in the turn to plan a multi-step goal with timeline_tasks |
reportMinutes | 3 (minutes) | Minimum time between timed reports; a report is written only after a turn ran since the last one |
Timed reports ask one question over the session's own conversation ($.model.fork), so they reuse its prompt cache but add to the session's cost.
Where the timeline is saved
Each session's timeline is one file, <config dir>/timeline/sessions/<session id>.json, where the config dir is $CLAUDE_CONFIG_DIR, else ~/.claude. The file holds a journal of every timeline_tasks call (time, tool-use id, subagent id, operations), the reports and the Discuss messages. The trees, the revisions and the cards are rebuilt from the journal.
- Resume (
--resume,--continue) reads the session's own file. - Fork (
--fork-session) finds the session file that shares calls with the forked conversation and keeps the calls the fork holds: the main conversation's calls and those of subagents it started. Reports and Discuss messages start over. - No file (deleted, or the mod was added later): the trees are rebuilt from the
timeline_taskscalls in the main conversation. Subagent changes are lost in this case, because a subagent's calls are not in the main conversation.
Known limitations
- While a permission dialog is open it takes the keys; Tab there edits the command. Answer the dialog before using the pane.
- The comment history keeps your Discuss messages only; Claude's answers stay in the conversation.
- When enabled, the mod hides
TodoWrite,TaskCreate,TaskUpdate,TaskListandTaskGetfrom the model. This has not been checked on a setup that offers those tools. - One file read or write is limited to 4 MiB, which bounds the journal of one session.
Develop
claude plugin test . # unit and kit tests in tests/
npx tsc -p . # type-check; the types appear in .claude-plugin/types/ once Claude Code has loaded the folder
claude plugin validate . # what the engine reads from the manifest and hooks
// faq
What is claude-timeline?
Timeline mods for Claude Code. It is open-source on GitHub.
Is claude-timeline free to use?
claude-timeline is open-source under the MIT license, so it is free to use.
What category does claude-timeline belong to?
claude-timeline is listed under plugins in the Claudeers registry of Claude-compatible tools.
// embed badge
[](https://claudeers.com/claude-timeline)
// retro hit counter
[](https://claudeers.com/claude-timeline)
// reviews
// guestbook
// related in Claude Plugins
A single CLAUDE.md file to improve Claude Code behavior, derived from Andrej Karpathy's observations on LLM coding pitfalls.
Claude Code is an agentic coding tool that lives in your terminal, understands your codebase, and helps you code faster by executing routine tasks, explainin…
"CLI-Anything: Making ALL Software Agent-Native" -- CLI-Hub: https://clianything.cc/
financial-services — a Claude ecosystem project on GitHub.