Palest Ink

Palest Ink

Overview

Palest Ink automatically records and indexes user activities, making it easy to review daily work, search for specific operations, and generate activity reports. Think of it as an intelligent activity journal that helps you track what you've done, when you did it, and what was accomplished.

Quick Start

Palest Ink stores all data in ~/.palest-ink/ with the following structure:

~/.palest-ink/
├── records.json          # All activity records
├── daily_reports/        # Generated daily reports
└── config.json           # Configuration (tags, categories, etc.)

First Time Setup

1. Initialize storage directory (automatic on first record)
2. Record activities using the CLI
3. Generate reports or query records as needed

Core Capabilities

1. Recording Activities

Record different types of activities:

Git Operations

# Record a git commit
palest-ink record git --message "Fix authentication bug" --repo my-app --commit abc123 --tags bugfix,auth

# Record a merge or PR work
palest-ink record git --message "Merge feature/user-profile" --repo my-app --pr 156 --tags feature,merge

Web Browsing

# Record visiting a webpage
palest-ink record web --url "https://example.com/docs/api" --title "API Documentation" --tags docs,reference

Command/Task

# Record a command or task
palest-ink record task --command "npm install package-name" --desc "Install dependencies" --tags setup

Custom Notes

# Free-form note
palest-ink record note --content "Discussed project timeline with team" --tags meeting

2. Querying Records

Search through your activity history:

By Type

# Find all git operations
palest-ink query --type git

# Find all web pages visited
palest-ink query --type web

By Keywords

# Search for records containing "plugin"
palest-ink query --keywords "plugin"

# Search multiple keywords
palest-ink query --keywords "plugin,authentication"

By Date Range

# Today's activities
palest-ink query --today

# Last 7 days
palest-ink query --days 7

# Specific date range
palest-ink query --from 2026-03-01 --to 2026-03-03

By Tags

# Records tagged "bugfix"
palest-ink query --tags bugfix

# Multiple tags (OR logic)
palest-ink query --tags "bugfix,feature"

# Require multiple tags (AND logic)
palest-ink query --tags "bugfix" --tags "plugin"

Combined Search

# Git commits mentioning "plugin" in last 7 days
palest-ink query --type git --keywords "plugin" --days 7

# Web pages about documentation from yesterday
palest-ink query --type web --tags docs --days 1

3. Generating Reports

Generate daily or periodic reports:

Daily Report

# Generate report for today
palest-ink report --day today

# Generate report for specific date
palest-ink report --day 2026-03-03

# Save report to file
palest-ink report --day today --output ~/Desktop/report.md

Weekly Summary

# Last 7 days summary
palest-ink report --week

# Custom range summary
palest-ink report --from 2026-03-01 --to 2026-03-07 --output weekly.md

Report Sections Reports include:

• Git operations (commits, merges, PRs)
• Web pages visited
• Commands/tasks executed
• Notes captured
• Tag-based groupings
• Time distribution by category

Usage Examples

Example 1: Track plugin development

# Record git work
palest-ink record git --message "Add plugin system" --repo my-app --tags plugin,feature
palest-ink record git --message "Fix plugin loading bug" --repo my-app --tags plugin,bugfix

# Query all plugin-related work
palest-ink query --keywords plugin --type git

Example 2: Find documentation you referenced

# Record web visits
palest-ink record web --url "https://docs.example.com" --title "API Docs" --tags docs
palest-ink record web --url "https://github.com/example/repo" --title "Repo" --tags reference

# Later, find all documentation visits
palest-ink query --type web --tags docs

Example 3: Generate daily work summary

# Throughout the day, record activities
palest-ink record git --message "Refactor auth module" --repo my-app --tags refactoring
palest-ink record task --command "pytest tests/" --desc "Run tests" --tags testing

# End of day, generate report
palest-ink report --day today --output ~/daily_report.md

Advanced Features

Tag Management

Define frequently-used tags in ~/.palest-ink/config.json:

{
  "tags": {
    "categories": ["bugfix", "feature", "refactoring", "docs", "testing"],
    "projects": ["my-app", "other-project"],
    "custom": []
  }
}

Automatic Capture

For frequent operations, consider shell aliases or git hooks:

Git post-commit hook example

#!/bin/bash
# .git/hooks/post-commit
COMMIT_MSG=$(git log -1 --pretty=%B)
palest-ink record git --message "$COMMIT_MSG" --repo $(basename $(git rev-parse --show-toplevel)) --commit $(git rev-parse HEAD)

Browser bookmarklet (manual)

// Bookmarklet to record current page
javascript:(function(){window.open('palest-ink://record/web?url='+encodeURIComponent(location.href)+'&title='+encodeURIComponent(document.title))})();

Best Practices

1. Record immediately - Capture activities as they happen, not retroactively
2. Use descriptive tags - Tags make searching much more effective
3. Include context - Add repo names, commit hashes, or full URLs
4. Regular reports - Generate weekly reports to track progress
5. Review and prune - Periodically clean up old or irrelevant records

Troubleshooting

Storage location not found?

• First record automatically creates ~/.palest-ink/
• Manually create: mkdir -p ~/.palest-ink/daily_reports

Query returns no results?

• Check date range with --days or specific dates
• Try broader keywords
• Use --list-tags to see all available tags

Report generation fails?

• Ensure records.json exists and is valid JSON
• Check output directory permissions
• Try with --day today for simplicity

Resources

scripts/

• palest-ink - Main CLI entry point (shell script)

  • Handles record, query, report subcommands
  • Manages JSON storage
  • Formats output

• record.py - Recording backend (Python)

  • Validates record formats
  • Updates records.json
  • Handles timestamps and IDs

• query.py - Search backend (Python)

  • Implements search logic
  • Supports filters (type, tags, date, keywords)
  • Returns structured results

• report.py - Report generator (Python)

  • Generates markdown reports
  • Groups by category and time
  • Calculates statistics