Metadata-Version: 2.4
Name: tliner
Version: 0.2.1
Summary: Timeliner 🌟 - AI's diary. Track AI agent work with markdown log
Author-email: "sinai.io" <r@sinai.io>
License: Proprietary
Keywords: ai-agents,fastmcp,logging,markdown,mcp,milestones
Requires-Python: >=3.11
Requires-Dist: aiohttp>=3.9.0
Requires-Dist: fastmcp==2.12.2
Requires-Dist: loguru==0.7.3
Requires-Dist: mdx-breakless-lists==1.0.1
Requires-Dist: mdx-truly-sane-lists==1.3
Requires-Dist: mkdocs-awesome-nav==3.2.0
Requires-Dist: mkdocs-gen-files==0.5.0
Requires-Dist: mkdocs-material==9.6.22
Requires-Dist: mkdocs==1.6.1
Requires-Dist: pydantic==2.11.7
Requires-Dist: python-frontmatter==1.1.0
Requires-Dist: typer==0.17.4
Provides-Extra: dev
Requires-Dist: pytest-mock==3.15.0; extra == 'dev'
Requires-Dist: pytest==8.4.2; extra == 'dev'
Description-Content-Type: text/markdown

# 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
- **Live documentation** - Auto-generated MkDocs site with search and navigation

## 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:
```bash
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](#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`)

## Documentation Browser (Experimental in v0.2.0)

Your timeline files automatically become a searchable doc-UI. Enable MkDocs by adding the `--mkdocs` flag to the "args" in your MCP server configuration.:

**In `.mcp.json`:**
```json
{
  "mcpServers": {
    "timeliner": {
      "command": "uvx",
      "args": ["tliner@latest", "serve", "--mkdocs"],
      "env": {"TIMELINER_WORK_FOLDER": "${PWD}/docs/timeline"}
    }
  }
}
```

Opens your browser to a live-updating docs site. Every time you save work, the site refreshes. Search anything, jump between tasks, copy file paths—it's all there.

**Quick tips:**
- Click task IDs or file paths to copy them
- Use the search box to find past work instantly
- "Open in Editor" buttons work with VSCode, Cursor, Zed, and 14 other editors

That's it. Write markdown, get docs.

>  **Note**: This feature is experimental and disabled by default. After testing and feedback, it will become core functionality (enabled by default) in v0.3.0.


---

## Advanced Usage

### CLI Commands

For manual inspection and debugging:

```bash
# 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
```

### Archiving Tasks

Got too many tasks cluttering your timeline? Just toss old ones into year-month folders like `2025_09`, `2025_10`, etc.

Everything still works—searches, retrieval, CLI commands—but now your root stays clean and MkDocs shows them organized by month. It's like filing papers in dated folders, except the computer remembers where everything is.

### Manual Installation

Add to `.mcp.json`:

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

Create `.claude/commands/save.md`:

```markdown
---
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). 
```
