Back to site
CommandChronicles logoCommandChronicles

CommandChronicles Documentation

Complete guide to architecture, security, and usage of the ultimate terminal history tracker.

Introduction

CommandChronicles is the ultimate terminal history tracker for developers, designed to capture, secure, and organize your command line experience. Unlike traditional shell history, CommandChronicles provides rich metadata, cross-device synchronization, and military-grade encryption.

Built with modern Go architecture, CommandChronicles offers real-time command capture, intelligent search capabilities, and seamless integration with your existing workflow. Every command is encrypted locally before storage, ensuring your sensitive information remains private and secure.

🔒 Secure by Design

XChaCha20-Poly1305 encryption with Argon2id key derivation

🔍 Intelligent Search

Fuzzy search with rich metadata and context

🌐 Cross-Device Sync

Perfect synchronization across all your devices

Installation & Setup

Download & Install

Download the latest release for your platform:

# Download from releases page
wget https://github.com/commandchronicles/cli/releases/latest/download/ccr-linux-amd64
chmod +x ccr-linux-amd64
sudo mv ccr-linux-amd64 /usr/local/bin/ccr

Available for Linux (amd64, arm64), macOS (Intel, Apple Silicon), and Windows

Initial Setup

After installation, set up CommandChronicles in 3 simple steps:

1
Initialize your setup
ccr init
2
Install shell hooks
ccr install-hooks
3
Start recording
Restart your shell and begin using!

Command Capture

Hook System Architecture

CommandChronicles uses shell integration hooks that automatically capture commands as you execute them. The system supports bash and zsh shells with transparent capture.

# Bash Hook Example
PROMPT_COMMAND="ccr record --pre; $PROMPT_COMMAND"
trap 'ccr record --post $?' DEBUG

Captured Data

Each command execution captures comprehensive metadata:

  • Command text and arguments
  • Exit code (success/failure)
  • Execution duration
  • Working directory
  • Git repository information
  • Session and hostname
  • User and shell type
  • Environment variables

Data Processing

Encryption Pipeline

All command data flows through a secure encryption pipeline before storage:

1
Command Capture
Raw command and metadata collection
2
Data Serialization
Convert to structured format with timestamps
3
Encryption
XChaCha20-Poly1305 authenticated encryption
4
Storage
Secure SQLite database with WAL mode

Search Engine

Hybrid Search Architecture

CommandChronicles implements a sophisticated hybrid search system combining exact matching with fuzzy search capabilities for optimal user experience.

🎯 Exact Search

  • • SQL-based pattern matching
  • • Directory and git filtering
  • • Exit code filtering

🔍 Fuzzy Search

  • • Bleve full-text indexing
  • • Typo tolerance
  • • Relevance scoring

Cache Implementation

High-performance caching system with configurable memory limits and intelligent eviction:

# Cache Configuration
hot_cache_size = 1000
search_batch_size = 100
max_memory_mb = 256
refresh_interval_seconds = 60

Background Daemon

Daemon Architecture

The background daemon handles automatic synchronization, maintenance tasks, and system integration. It runs as a lightweight service with minimal resource usage.

🔄
Auto Sync
Background synchronization
🧹
Maintenance
Cache cleanup & optimization
📊
Monitoring
Health checks & metrics

Daemon Control

ccr daemon-control start
ccr daemon-control stop
ccr daemon-control status
ccr daemon-control restart
ccr daemon-control install-service
ccr daemon-control remove-service

Security Implementation

XChaCha20-Poly1305 Encryption

CommandChronicles uses XChaCha20-Poly1305, a state-of-the-art authenticated encryption algorithm that provides both confidentiality and integrity protection.

Key Features:

  • • 256-bit key size
  • • 192-bit nonce (extended nonce)
  • • Authenticated encryption
  • • Resistance to timing attacks

Security Benefits:

  • • Data confidentiality
  • • Data integrity verification
  • • Protection against forgery
  • • Large nonce space prevents collisions

Argon2id Key Derivation

Key Derivation Process

User passwords are strengthened using Argon2id, the winner of the Password Hashing Competition and recommended by OWASP for password storage.

Default Parameters:

Time: 3 iterations
Memory: 64 MB
Threads: 4

Privacy Model

✓ What We Protect:

  • • All command history data
  • • Working directories and paths
  • • Git repository information
  • • Environment variables
  • • User session data

🛡️ How We Protect:

  • • Local-only storage by default
  • • End-to-end encryption for sync
  • • Secure session management
  • • No telemetry or tracking
  • • Memory protection & cleanup

Basic Commands

Installation and Setup

ccr setup

Initialize CommandChronicles with default configuration and create necessary directories

ccr install-hooks

Install shell integration hooks for automatic command capture (bash/zsh)

ccr uninstall-hooks

Remove shell hooks to disable automatic command recording

Authentication

Session Management

ccr login

Authenticate and create a new session (required for encrypted operations)

ccr lock

Lock the current session and require re-authentication

ccr unlock

Unlock with password and restore session access

Search Operations

Interactive Search

Ctrl+R

Launch interactive TUI for command search and selection (when hooks are installed)

ccr tui

Launch TUI directly (view-only mode without command injection)

Command Line Search

ccr search [query]

Search command history with fuzzy matching and filters

ccr search --directory /path [query]

Filter search results by working directory

ccr search --success-only

Show only commands that executed successfully (exit code 0)

Tag System

Command Organization with Tags

Tags are short labels that help categorize and organize your commands for better discoverability. CommandChronicles supports both manual tagging and automatic tag assignment based on command patterns.

Manual Tagging

ccr tag add 123 deployment
ccr tag add 123 production
ccr tag search docker

Auto-Tagging

docker → docker
git → git
kubectl → k8s

TUI Tag Features

Keyboard shortcuts

  • ctrl+g - Manage tags for selected command
  • ctrl+f+g - Toggle tag search mode
  • ctrl+t - Access color picker for tags
  • ctrl+a - Auto-tag rules management

Visual Features

  • • Colored tag labels for visual grouping
  • • Up to 5 tags per command
  • • 16 color palette for customization
  • • Integrated search by tags

Notes System

Contextual Command Documentation

Add detailed notes to any command explaining why you ran it and how it solved your problem. Transform your command history into a personal knowledge base with rich context and explanations.

CLI Note Management

ccr note add 123 "Deploy to production"
ccr note edit 123 "Updated deployment"
ccr note search "deployment"

TUI Note Features

ctrl+n - Edit note for selected command
ctrl+f+n - Search commands and notes
tab - View command details with notes

Best Practices for Notes

What to include

  • • Context: Why was this command run?
  • • Solution: What problem did it solve?
  • • Environment: Which server/environment?
  • • Parameters: Important flags or options

Note Features

  • • Maximum 1000 characters per note
  • • Multi-line support with word wrapping
  • • Visual indicators (● dot) for noted commands
  • • Combined search with command text

Data Management

Import/Export Operations

ccr export --format json

Export complete command history with metadata in JSON format

ccr import ~/.bash_history --format bash

Import existing shell history from standard history files

ccr delete --id [command-id]

Delete specific commands from encrypted storage

Sync Operations

Cross-Device Synchronization

ccr sync register

Register device for cross-device sync with CommandChronicles servers

ccr sync now

Sync local command history with server ( pull / push )

ccr sync pull

Pull command history from other synchronized devices

Daemon Control

ccr daemon-control start
ccr daemon-control stop
ccr daemon-control status
ccr daemon-control restart
ccr daemon-control install-service
ccr daemon-control remove-service

Configuration

Config File Structure

Configuration is stored in ~/.config/commandchronicles/config.toml

# Database Configuration
[database]
path = "~/.local/share/commandchronicles/commands.db"
max_open_conns = 25
max_idle_conns = 25
wal_mode = true

# Cache Settings
[cache]
hot_cache_size = 1000
search_batch_size = 100
max_memory_mb = 256

# Security Configuration
[security]
session_timeout = "90d"
argon2_time = 3
argon2_memory = 65536
argon2_threads = 4

Environment Variables

[Content placeholder: Available environment variables and their usage]

Troubleshooting

Common Issues

Shell Integration Not Working

If commands aren't being captured after installation:

# Restart your shell or source your RC file
source ~/.bashrc # For bash
source ~/.zshrc # For zsh
# Or reinstall hooks with auto-detection
ccr install-hooks --auto

Search Not Finding Commands

If your search isn't returning expected results:

  • • Check if the search index needs rebuilding with ccr rebuild-index
  • • Verify commands are being captured with ccr stats
  • • Try exact matching before fuzzy search
  • • Ensure you're using the correct shell where hooks are installed

Sync Issues

If cross-device sync is not working properly:

# Check daemon status
ccr daemon-control status
# Restart sync daemon
ccr daemon-control restart
# Force manual sync
ccr sync now

Memory and Performance

If CommandChronicles is using too much memory or feels slow:

  • • Adjust cache settings in ~/.config/commandchronicles/config.toml
  • • Reduce hot cache size if memory usage is high
  • • Consider archiving old command history
  • • Check if search index needs optimization

Permission Issues

If you're getting permission errors:

  • • Ensure ~/.local/share/commandchronicles/ is writable
  • • Check that ~/.config/commandchronicles/ exists and is accessible
  • • Verify your user has permission to write to the shell RC files
  • • Try running ccr debug to diagnose issues

Getting Help

If you're still experiencing issues:

Community Support

Direct Support

Troubleshooting

Common Issues

[Content placeholder: FAQ-style troubleshooting guide]

Debug Mode

[Content placeholder: How to enable debugging and log analysis]

CommandChronicles logo

CommandChronicles

The ultimate terminal history tracker for developers.
Never lose a command again. Ever

Product

Resources

Community

© 2025 CommandChronicles. All rights reserved.