ccjournal 0.3.0
Sync Claude Code conversation logs to Git repository
Requires Python: >=3.11
Keywords: claude, claude-code, git, logging, sync

# ccjournal

Sync Claude Code conversation logs to a Git repository.

[日本語](README_ja.md)

## 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](https://cli.github.com/)
  - 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

```bash
pipx install ccjournal
# or
uv tool install ccjournal
```

## Quick Start

```bash
# 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:**

```toml
[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](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)

```bash
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

```bash
# 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](https://support.apple.com/guide/mac-help/open-a-mac-app-from-an-unknown-developer-mh40616/mac)

**Option 2: Remove quarantine attribute**

```bash
# 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:
```bash
launchctl unload ~/Library/LaunchAgents/com.ccjournal.daemon.plist
launchctl load ~/Library/LaunchAgents/com.ccjournal.daemon.plist
```

See: [Apple Developer Forums - Avoiding notarisation & Gatekeeper](https://developer.apple.com/forums/thread/666452)

## Development

```bash
# 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