tliner 0.1.9

Timeliner 🌟 - AI's diary. Track AI agent work with markdown log

Timeliner

Auto-documenting memory layer for AI coding agents. Timeliner logs your AI development sessions as timestamped markdown files, giving AI agents perfect recall of past decisions, implementations, and context.

Feature Highlights

• Zero-friction logging - easy-save work via /save command
• Rich context - Capture outcomes, tags, metadata (PRs, commits, issues)
• Markdown storage - Human-readable logs
• MCP integration - Works with Claude Code, RooCode, and other MCP-enabled tools

Use Cases

Software Development:

• Document decisions and rationale during coding sessions
• Track refactoring steps
• Log implementation progress

Research & Learning:

• Maintain experiment logs with results and insights
• Build a learning journal
• Track hypothesis evolution

Installation

Automatic Setup for Claude Code

• Run the installer command in your project root:

uvx --from tliner@latest tliner-install

• Automatically configures .mcp.json and creates /save and /report commands in .claude/commands/
• Documents wil be stored in docs/timeline/ by default.
• To specify a different storage folder, use uvx --from tliner@latest tliner-install --work-folder <PATH_TO_STORE_DOCS>.

Manual Setup for Other MCP Tools

See Manual Installation below.

Quick Start

Using the /save Command

1. Run /save in your Agent Tool, when you feel you have made significant progress or decisions.
2. File will be created/updated in your configured TIMELINER_WORK_FOLDER (docs/timeline/ by default).

Using the /report Command

Generate work reports analyzing your Timeline task files: /report <topic> [time_period]

Examples:

• /report "authentication bug" "last 2 days" - Find work on authentication in recent files
• /report work done (concise summary) last week - Generate summary of all work from last week

The report groups related work into distinct approaches, showing implementation attempts, outcomes, and current status.

Configuration

Environment Variables

• TIMELINER_WORK_FOLDER: Storage directory (default: work/docs)

---

Advanced Usage

CLI Commands

For manual inspection and debugging:

# List all tasks
TIMELINER_WORK_FOLDER="${PWD}/docs/timeline" uvx tliner@latest task-list

# Show all steps for a task
TIMELINER_WORK_FOLDER="${PWD}/docs/timeline" uvx tliner@latest task-show <task_id>

# Run MCP server manually
TIMELINER_WORK_FOLDER="${PWD}/docs/timeline" uvx tliner@latest serve

Manual Installation

Add to .mcp.json:

{
  "mcpServers": {
    "timeliner": {
      "type": "stdio",
      "command": "uvx",
      "args": ["tliner@latest", "serve"],
      "env": {"TIMELINER_WORK_FOLDER": "${PWD}/docs/timeline"}
    }
  }
}

Create .claude/commands/save.md:

---
description: "Save findings/outcomes into a Timeline"
---
# Save Command
Execute the save operation according to the next rules.
## Flow
1.  **Generate Content**:
    *   Generate the outcomes for the current step following the "Content Structure" and "Rules".
2.  **Save to Timeliner**:
    *   Call `mcp__timeliner__save_step` with the following parameters:
        *   `task_id`: Use the memorized `task_id` if you have one. If this is the first time saving for this task, send an **empty string** (`""`). The system will create a new task and return the new `task_id`.
        *   `title`: Up to 5 words which represent essence of the step.
        *   `outcomes`: The exact content that you just generated.
    *   **VERY IMPORTANT**: If a new `task_id` is returned, you MUST memorize it for all future `save_step` calls for this task.
    
## Content Structure

1. **Summary**: Describe current step summary and general flow of investigation.
2. **Facts**: Main goal is describing outcomes as facts with GREAT details (not only summary).
3. **User Input**: Note ALL user's input and direction they want to go.
4. **Resources**: Note ALL resources used (files, links, tools, commands, etc) with direct links (full path/URL/command).

## Rules
1. **Avoids**: NO hypothesis, NO assumptions, NO speculations, NO generalizations. Facts ONLY.
2. **Evidence**: Including evidences for statements is mandatory:
    - Link to source files with line numbers: `[cmd line flags](../src/go/flags.go#L94)`
    - Links to external resources: `[config docs](https://example.com/docs/setup.html)`
3. **Structure**: 
    - All main sections within the `outcomes` (e.g., Summary, Facts, User Input) MUST start with a level 2 heading (`##`). Do NOT use level 1 headings.
    - Fit all outcomes in ONE chapter, don't split into several chapters.
    - Use sub-sections inside the `Facts` chapter only. Every fact must be the level 3 heading (`###`). 
    - Do not use level 4 and higher headings. Use multi-level numerated/bullet lists instead ("outliner" style).