ccjournal 0.3.0

Sync Claude Code conversation logs to Git repository

ccjournal

Sync Claude Code conversation logs to a Git repository.

日本語

Prerequisites

Required

• Python 3.11+
• Git - for committing and pushing logs
• Claude Code - this tool syncs logs generated by Claude Code

Optional

• GitHub CLI (gh) - required for public repository detection
  • Install: brew install gh (macOS) or see GitHub CLI installation
  • Authenticate: gh auth login

Features

• Automatically sync Claude Code session logs to a Git repository
• Organize logs by date or project
• Support for worktrees (groups by Git remote URL)
• Auto-commit and push to remote
• Configurable via TOML

Installation

pipx install ccjournal
# or
uv tool install ccjournal

Quick Start

# Initialize configuration
ccjournal init

# Manually sync logs
ccjournal sync

# Show configuration
ccjournal config show

Configuration

Configuration file is located at ~/.config/ccjournal/config.toml.

Quick reference:

[output]
repository = "~/Documents/claude-logs"
structure = "date"                    # "date" or "project"
auto_push = true
allow_public_repository = false       # Security: block push to public repos
allow_unknown_visibility = false      # Security: block push when visibility unknown

[sync]
interval = 300                        # seconds (for daemon)
exclude_system = true                 # exclude system messages
exclude_tool_messages = true          # exclude [Tool: XXX] only messages

[projects.aliases]
"/path/to/project" = "custom-name"    # optional: customize project names

For complete configuration reference, see docs/configuration.md.

Security

Fail-Safe Design

ccjournal includes multiple security layers to prevent accidental exposure of sensitive information:

1. Public repository protection - Blocks push to public repositories by default
2. Unknown visibility protection - Blocks push when visibility cannot be determined (non-GitHub repos)
3. Sensitive data masking - Automatically masks API keys, tokens, passwords in output

Public Repository Protection

By default, ccjournal blocks pushing to public repositories to prevent accidental exposure of sensitive information that may be included in conversation logs, such as:

• API keys or passwords mentioned in prompts
• Internal URLs (Notion, Confluence, etc.)
• Confidential discussion content

If the output repository is detected as public on GitHub, the sync will fail with an error:

Error: Refusing to push to public repository: /path/to/repo

Note: Public repository detection requires GitHub CLI (gh). For non-GitHub repositories, set allow_unknown_visibility = true after confirming the repository is private.

Directory Structure

Date-based (default):

claude-logs/
└── 2026/01/16/
    ├── my-project.md
    └── another-repo.md

Project-based:

claude-logs/
└── github.com-user-my-project/
    ├── 2026-01-16.md
    └── 2026-01-15.md

Commands

Command	Description
ccjournal init	Initialize configuration interactively
ccjournal sync	Sync logs to repository
ccjournal sync --dry-run	Preview what would be synced
ccjournal sync --date 2026-01-16	Sync specific date
ccjournal config show	Show current configuration
ccjournal config edit	Open config in editor
ccjournal list	List recent synced logs
ccjournal daemon install	Install daemon as system service
ccjournal daemon uninstall	Uninstall daemon service

Automatic Sync

macOS (launchd)

ccjournal daemon install

Follow the instructions to set up automatic sync every 5 minutes.

Linux (systemd)

Create user services for periodic sync. See ccjournal daemon install for details.

cron

# Sync every 5 minutes
*/5 * * * * /usr/local/bin/ccjournal sync

Troubleshooting

macOS: "unidentified developer" warning

When running ccjournal daemon install, macOS may show a security warning because the package is not signed with an Apple Developer ID.

Option 1: Allow via System Settings (Apple recommended)

1. Open "System Settings" → "Privacy & Security"
2. Find the blocked app and click "Open Anyway"

See: Open a Mac app from an unknown developer - Apple Support

Option 2: Remove quarantine attribute

# Remove quarantine attribute from ccjournal
xattr -dr com.apple.quarantine ~/.local/bin/ccjournal
xattr -dr com.apple.quarantine ~/.local/share/uv/tools/ccjournal/

Then reload the service:

launchctl unload ~/Library/LaunchAgents/com.ccjournal.daemon.plist
launchctl load ~/Library/LaunchAgents/com.ccjournal.daemon.plist

See: Apple Developer Forums - Avoiding notarisation & Gatekeeper

Development

# Clone the repository
git clone https://github.com/TAKEDA-Takashi/ccjournal.git
cd ccjournal

# Install dependencies
uv sync --dev

# Run tests
uv run pytest

# Type check
uv run pyright

# Lint
uv run ruff check

License

MIT