Agent Worklog

Spiritual fork of https://github.com/adriancooney/agent-worklog

A lightweight system for tracking, logging, and analyzing work performed by AI coding agents.

Quick Start: Using in Your Projects

Once installed, Agent Worklog works automatically across all your projects. Here's how to use it:

1. Use the <work> Trigger

Simply include <work> in any prompt to your AI coding agent. The agent will:

1. Complete your requested task
2. Create a git commit
3. Log the work to a central database

Examples:

<work> Add user authentication to the API #feature #security

<work> Fix the pagination bug in the search results #bugfix

<work> Refactor database queries for better performance #refactor #performance

2. Add Hashtags for Organization

Hashtags help categorize and search your work later:

Tag	Use For
#feature	New functionality
#bugfix	Bug fixes
#refactor	Code refactoring
#docs	Documentation
#test	Test additions
#api	API changes
#ui	User interface
#security	Security-related

3. Query Your Work History

Use the CLI to review past work:

# See recent work across all projects
agent-worklog list

# Filter by project
agent-worklog list -r my-project

# Filter by tag
agent-worklog list --tag "#bugfix"

# Get statistics
agent-worklog stats --since 2026-01-01

4. Works Everywhere

The worklog database lives at ~/.agent-worklog.db (in your home directory), so:

• Works across all your git repositories
• Survives fresh clones and new projects
• No per-project setup needed

---

Overview

Agent Worklog provides a structured way to maintain an audit trail of AI agent contributions across coding sessions and projects. It enables:

• Work Logging: Record completed tasks with git metadata and code change statistics
• Summarization: Generate performance reviews and summaries over any timeframe
• Querying: Search historical work using natural language questions

Installation

Quick Install

Clone the repo and run the installer:

git clone https://github.com/your-username/agent-worklog.git
cd agent-worklog
./install.sh

The installer will:

1. Initialize the SQLite database
2. Create a Cursor rule at ~/.cursor/rules/always-agent-worklog.mdc
3. Add the bin/ directory to your PATH in ~/.zshrc

Manual Installation

If you prefer manual setup:

# 1. Clone the repository
git clone https://github.com/your-username/agent-worklog.git
cd agent-worklog

# 2. Initialize the database
python3 init_db.py

# 3. Add to PATH (add this to ~/.zshrc or ~/.bashrc)
export PATH="$PATH:/path/to/agent-worklog/bin"

# 4. Reload shell
source ~/.zshrc

Verify Installation

Open a new terminal and run:

agent-worklog

You should see the help output with configuration paths.

For AI Agents

After installation, AI agents using Cursor will automatically have access via the .mdc rule. For other setups, point your agent to the AGENTS.md file.

Uninstall

./install.sh --uninstall

Project Structure

agent-worklog/
├── AGENTS.md           # LLM instructions index
├── README.md           # This file
├── PRD.txt             # Product requirements document
├── progress.txt        # Development progress tracker
├── install.sh          # Installation script
├── schema.sql          # Database schema
├── init_db.py          # Database initialization script
├── bin/
│   └── agent-worklog   # CLI tool
└── skills/
    ├── do_work.md          # Skill: Complete workflow with auto-logging
    ├── log_work.md         # Skill: Log completed work
    ├── summarize_work.md   # Skill: Generate summaries
    └── query_work.md       # Skill: Query historical work

~/.agent-worklog.db         # SQLite database (in home directory, survives fresh clones)

CLI Usage

The agent-worklog CLI provides commands for managing work entries:

agent-worklog                     # Show help and configuration
agent-worklog init                # Initialize database
agent-worklog log [OPTIONS]       # Log a work entry
agent-worklog list [OPTIONS]      # List work entries
agent-worklog show <id>           # Show entry details
agent-worklog stats [OPTIONS]     # Show statistics

Log a Work Entry

# Auto-detect git info from current directory
agent-worklog log -t "Implemented user authentication" -H "#feature,#auth"

# Specify project path
agent-worklog log -t "Fixed login bug" -p /path/to/project -H "#bugfix"

# Manual entry (no git)
agent-worklog log -t "Code review" --no-git -H "#review"

List Entries

# List recent entries
agent-worklog list

# Filter by tag
agent-worklog list --tag "#feature"

# Filter by date range
agent-worklog list --since 2026-01-01 --until 2026-01-31

# Output as JSON
agent-worklog list --json

View Statistics

# Overall stats
agent-worklog stats

# Stats for a time period
agent-worklog stats --since 2026-01-01

# Stats for a specific project
agent-worklog stats -p /path/to/project

Skills

Do Work (skills/do_work.md) - Primary Workflow

Triggered when a prompt contains <work>. Executes the complete workflow:

1. Parse task and extract hashtags from prompt
2. Execute the coding task
3. Create git commit
4. Log work to database

Example prompt:

<work> Add input validation to signup form #feature #validation

Hashtags are automatically extracted from the prompt (excluding code blocks and non-tags like #123 or CSS selectors).

Log Work (skills/log_work.md)

Records a work entry at the end of a coding task.

Fields captured:

• Task description
• Project root path
• Git ref (branch)
• Commit hash
• Lines added/removed
• Commit message
• Hashtags for categorization
• Timestamp
• Worktree path

Example usage (by agent):

import sqlite3
from datetime import datetime

conn = sqlite3.connect('worklog.db')
cursor = conn.cursor()
cursor.execute('''
    INSERT INTO worklog (task, project_root, git_ref, commit_hash,
                         lines_added, lines_removed, commit_message,
                         hashtags, timestamp, worktree)
    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
''', (
    "Implemented user authentication",
    "/Users/dev/myproject",
    "main",
    "abc123def",
    150,
    20,
    "feat: add user auth system",
    "#feature,#auth,#security",
    datetime.utcnow().isoformat() + "Z",
    "/Users/dev/myproject"
))
conn.commit()
conn.close()

Summarize Work (skills/summarize_work.md)

Generates summaries and performance reviews for a timeframe.

Outputs:

• Tasks completed count and list
• Total commits and code changes
• Performance review narrative
• Breakdown by hashtags
• Commit hashes for diff retrieval

Example query:

SELECT 
    COUNT(*) as tasks,
    SUM(lines_added) as added,
    SUM(lines_removed) as removed
FROM worklog 
WHERE timestamp BETWEEN '2026-01-01' AND '2026-01-31';

Query Work (skills/query_work.md)

Retrieves relevant work entries via natural language queries.

Example queries:

• "What authentication work was done last month?"
• "Show me all bugfixes in the API project"
• "Find the largest code changes this week"
• "What did I work on yesterday?"

Database Schema

CREATE TABLE worklog (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    task TEXT NOT NULL,
    project_root TEXT NOT NULL,
    repo TEXT NOT NULL,           -- Repository name (from git remote or directory)
    project TEXT NOT NULL,        -- Project/directory name
    worktree TEXT,
    git_ref TEXT,
    commit_hash TEXT,
    commit_message TEXT,
    lines_added INTEGER DEFAULT 0,
    lines_removed INTEGER DEFAULT 0,
    hashtags TEXT,
    timestamp TEXT NOT NULL,
    created_at TEXT DEFAULT CURRENT_TIMESTAMP
);

Indexes: timestamp, project_root, repo, project, hashtags, commit_hash

Views:

• worklog_stats: Daily statistics
• project_stats: Per-project summaries

Hashtag Conventions

Use consistent hashtags to categorize work:

Tag	Use For
#feature	New functionality
#bugfix	Bug fixes
#refactor	Code refactoring
#docs	Documentation
#test	Test additions
#config	Configuration changes
#deps	Dependency updates
#security	Security-related
#performance	Performance improvements
#ui	User interface changes
#api	API changes
#database	Database changes

For AI Agents

1. Read AGENTS.md first - It provides an overview and links to all skills
2. Use the appropriate skill for the task at hand
3. Follow the step-by-step instructions in each skill file
4. Always use ISO 8601 timestamps (e.g., 2026-01-21T14:30:00Z)
5. Include relevant hashtags for better querying later

Manual Database Queries

You can query the database directly for quick lookups:

# Open database
sqlite3 worklog.db

# View recent entries
SELECT task, timestamp, hashtags FROM worklog ORDER BY timestamp DESC LIMIT 10;

# View daily stats
SELECT * FROM worklog_stats LIMIT 7;

# View project summary
SELECT * FROM project_stats;

Requirements

• Python 3.6+
• SQLite3 (included with Python)

No additional dependencies required.

License

MIT