Frequently Asked Questions
Everything you need to know about CommandChronicles
How it Works
How does CommandChronicles capture my commands?
CommandChronicles uses shell integration hooks that automatically capture commands as you execute them. Here's how it works:
ccr install-hooks, the CLI generates shell-specific hook scripts for bash or zshccr record commandThe capture process is completely transparent - you don't need to do anything once the hooks are installed.
What data does it capture?
The hooks intercept your commands and capture:
- • The actual command text
- • Exit code (success/failure)
- • Execution duration
- • Working directory
- • Git repository information (if applicable)
- • Timestamp and session information
- • Hostname and user
- • Shell type
- • Environment variables
- • Git branch and commit (when in repo)
Shell Integration
How do I install shell hooks?
After installing CommandChronicles, set up shell integration:
Then restart your shell. CommandChronicles will automatically detect your shell type (bash/zsh) and install the appropriate hooks.
Can I uninstall the hooks?
Yes, you can temporarily or permanently disable command capture:
Information & Help
Additional TUI Features
Tab- View detailed command information (duration, directory, git info)Ctrl+T- View command statistics?- Show help and all available keybindings
Important Note: Command injection (Enter/Ctrl+J) only works when the TUI is launched via Ctrl+R after installing shell hooks. Running ccr tui directly will show the interface but cannot inject commands into your shell.
Security & Privacy
Is my command history secure?
Yes, CommandChronicles implements military-grade security:
- • Local-Only Storage: All data is stored locally on your machine - no cloud services or telemetry
- • Full Encryption: Every command is encrypted using XChaCha20-Poly1305 before storage
- • Secure Authentication: Password-based access with Argon2id key derivation
- • Session Management: Configurable session timeouts with automatic cleanup
- • Memory Protection: Sensitive data is cleared from memory after use
Encryption
What encryption does CommandChronicles use?
CommandChronicles uses state-of-the-art cryptography:
Encryption Algorithm
- • XChaCha20-Poly1305 (authenticated encryption)
- • 256-bit key size
- • 192-bit nonce (extended nonce)
- • Resistance to timing attacks
Key Derivation
- • Argon2id with configurable parameters
- • Default: 3 iterations, 64MB memory
- • 256-bit session keys
- • Configurable timeout (default: 90 days)
Privacy Controls
Can I exclude sensitive commands?
Currently, CommandChronicles captures all commands executed in shells with installed hooks. However, you can:
- • Lock Your History: Use
ccr lockto require password authentication for searches - • Delete Specific Commands: Use
ccr deleteto remove sensitive commands from history - • Disable Temporarily: Uninstall hooks temporarily with
ccr uninstall-hooks - • Session Control: End sessions cleanly to compartmentalize sensitive work
Future versions may include command filtering and exclusion patterns.
Cross-Device Sync
How does cross-device sync work?
CommandChronicles offers optional cross-device synchronization with perfect integrity:
ccr sync registerHow much data does sync use?
Sync usage is minimal and efficient:
- • Command Data: Typically 100-500 bytes per command (depending on length and metadata)
- • Incremental Sync: Only new/changed commands are synchronized
- • Compression: Data is compressed during transmission
- • Estimated Usage: For heavy users (1000 commands/day), expect ~150KB/day of sync data
Offline Usage
Can I use CommandChronicles offline?
Absolutely! CommandChronicles is designed to work offline-first:
- • Local Storage: All core functionality works without internet connection
- • Search & TUI: Full search capabilities available offline
- • Command Recording: Continues capturing commands offline
- • Sync Queue: Changes are queued and synchronized when connection is restored
- • Independent Operation: Each device maintains a complete local copy of your history
Daemon Management
How do I control the background daemon?
ccr daemon-control startStart background sync daemon
ccr daemon-control stopStop background sync daemon
ccr daemon-control statusCheck daemon status
ccr daemon-control restartRestart daemon with new settings
ccr daemon-control install-serviceInstall system service for automatic startup
ccr daemon-control remove-serviceRemove system service
Data Storage
Where is my data stored?
CommandChronicles stores data in standard system locations:
- • Configuration: ~/.config/commandchronicles/config.toml
- • Database: ~/.local/share/commandchronicles/commands.db
- • Session Keys: ~/.local/share/commandchronicles/session.key
- • Shell Hooks: ~/.local/share/commandchronicles/hooks/
- • Search Index: ~/.local/share/commandchronicles/search_index/ (for fuzzy search)
All files are created with secure permissions (mode 0700/0600) to prevent unauthorized access.
Storage Usage
How much storage space does it use?
Storage usage depends on your command history volume:
Storage Breakdown
- • Database Overhead: ~50KB for empty database with schema
- • Per Command: ~200-800 bytes (depending on command length and metadata)
- • Search Index: ~2-5x the database size (for fuzzy search capabilities)
Example Usage
- • 10,000 commands ≈ 5-8MB total storage
- • Heavy user (1000 cmd/day) ≈ 1-2MB/day
- • Automatic cleanup available
Backup & Export
Can I backup or export my data?
Yes, CommandChronicles provides comprehensive export options:
Export Formats
ccr export --format jsonComplete data with metadata
ccr export --format bashPlain bash history format
ccr export --format csvSpreadsheet-compatible format
Import Options
ccr import ~/.bash_history --format bashccr import ~/.zsh_history --format zshNote: Exported data includes timestamps, directories, exit codes, and git information, making it more comprehensive than standard shell history files.
Getting Help
Need additional help?
If you need additional help beyond this FAQ:
- • Run
ccr --helpfor command-line help - • Use
?in the TUI for interactive help - • Check the technical documentation for detailed information
- • Visit commandchronicles.dev for more resources
