---
title: "CommitBook"
url: https://zaai.com/commitbook/
description: "Automated git commits and sync for your Markdown notes. Turn any git repository into a self-saving, self-syncing note-taking workspace."
---

![CommitBook stacked pages and saved-history timeline](https://zaai.com/commitbook/commitbook-product-icon.svg) Rust CLI · macOS / Linux

# Write in Markdown.  
CommitBook runs the git.

Automated git commits and sync for your Markdown notes. Turn any git repository into a self-saving, self-syncing note-taking workspace.

[View on GitHub](https://github.com/CommitBook/CommitBook-Core) [Read the docs](https://github.com/CommitBook/CommitBook-Core/blob/main/docs/README.md)

Offline-first No CommitBook server MIT licensed

brew install commitbook/tap/commitbook

Requires Homebrew on macOS or Linux.  
Install on each computer, then [set up your notes repository](#workflow-2).

Features

## What CommitBook handles

### Scheduled sync

Run commitbook sync on a schedule using launchd on macOS or cron on Linux. Choose a preset or a supported five-field cron expression.

### Local commits while offline

Saved changes are committed even when the remote is unreachable. A later sync fetches and pushes when the connection returns.

### Sync through your Git remote

Fetch remote changes, merge them into the local branch, and push local commits. Use the same repository on each computer.

### Optional AI commit messages

Use timestamp messages by default, or ask an installed AI CLI to summarize changes. Failed AI requests fall back to timestamps.

### Configurable conflict handling

Keep both versions of text notes, resolve conflicts manually, or use AI with or without approval. Choose a mode per repository.

### Repository-local configuration

Settings live in .CommitBook/config.toml. Device-local state is gitignored. No separate CommitBook server or database is required.

Workflow

## Set up your notes repository

1.  01
    
    ### Install with Homebrew
    
    Install the CLI on each computer where you keep your notes.
    
    terminal
    
    ```bash
    brew install commitbook/tap/commitbook
    ```
    
2.  02
    
    ### Initialize your notes repository
    
    Open an existing Git repository with a configured remote. Initialization creates .CommitBook/, registers this computer, and commits the metadata. Repeat on each computer.
    
    terminal
    
    ```bash
    cd ~/my-notes
    commitbook init
    ```
    
3.  03
    
    ### Configure and start syncing
    
    Run a sync to check your remote connection, then enable hourly runs. Your Git credentials must work without an interactive prompt.
    
    terminal
    
    ```bash
    commitbook sync
    commitbook schedule 1h
    commitbook start
    ```
    
4.  04
    
    ### Write in your preferred Markdown editor
    
    Open the repository in your Markdown editor and save your files as usual. CommitBook commits saved changes on its schedule; it does not save unsaved editor buffers.
    
    Markdown editor · journal.md
    
    \# Sunday notes
    
    Document the sync setup.  
    Draft next week’s reading list.
    
5.  05
    
    ### Check sync status
    
    Run commitbook status from the repository to inspect local changes, remote sync state, and scheduler health.
    
    terminal
    
    ```bash
    commitbook status
    ```
    

What a sync looks like

## Commit locally. Fetch. Merge. Push.

Each sync commits your saved changes, fetches changes from the remote, merges them into your local branch, and pushes the result. Without a connection, local commits still work. Remote sync resumes on a later run.

commitbook · notes Example · 2 computers

Laptop

Local notes + CommitBook

↔ Git remote ↔

Shared repository

Desktop

Local notes + CommitBook

```console
$ commitbook sync

Example: a sync on the laptop

1. Commit   Save changed files in local Git history
2. Fetch    Download commits pushed by the desktop
3. Merge    Combine remote changes with local commits
4. Push     Upload the result to the shared remote

The desktop gets these changes on its next sync.
```

1 CommitBook · 2 computers · hourly schedule · Each computer syncs independently

Commands

## CLI reference

| Command | Description |
| --- | --- |
| `commitbook init` | Initialize `.CommitBook/`; required before anything else |
| `commitbook sync` | Commit saved changes, fetch, merge, and push. Also used by scheduled runs. |
| `commitbook preview` | List the files the next snapshot would include |
| `commitbook start` | Start the sync scheduler (launchd / cron) |
| `commitbook stop` | Stop the scheduler |
| `commitbook schedule <expr>` | Change the sync schedule (preset or cron) |
| `commitbook status` | Sync state, schedule, devices, and config at a glance |
| `commitbook devices` | List syncing devices; rename this one, remove others |
| `commitbook doctor` | Check system health and installed AI agents |
| `commitbook log` | View recent activity |
| `commitbook completions <shell>` | Shell completions for your shell |

Scheduling

## Choose a sync schedule

Use a preset or a supported five-field cron expression. CommitBook uses launchd on macOS and cron on Linux, with no persistent CommitBook daemon.

`5m` `15m` `30m` `1h` `2h` `4h` `daily` `0 * * * *`

1h is the default, equivalent to 0 \* \* \* \* (every hour, at minute 0). daily runs at 9:00 AM. Commits are created only when Git reports changes.

terminal

```bash
# Hourly; equivalent to 0 * * * *
commitbook schedule 1h
commitbook start

# Pause scheduled syncs
commitbook stop
```

AI, optionally

## Choose how commits are named

Timestamp messages are the default. To enable AI messages, edit the \[commit\] section in .CommitBook/config.toml. This setting is shared through the repository.

### Timestamp · default

No AI required

```toml
[commit]
mode = "timestamp"

# → Writing 2026-09-27 14:30:02
```

### AI · opt-in

agent-written

```toml
[commit]
mode = "ai"
agent = "claude"

# → Summarize sync UX notes;
#    tighten schedule copy
```

AI messages use an installed and authenticated CLI. If the configured agent is missing or fails, CommitBook uses a timestamp message instead.

### Use an installed AI CLI

Supported agents run through their local CLIs. Install and authenticate the agent you choose, then opt in per repository. Timestamp mode does not invoke an AI agent for commit messages.

GitHub Copilot Claude Code Codex Gemini Cursor

`agent = "any"` tries installed agents in the order shown until one succeeds, then falls back to a timestamp if none succeeds.

```bash
# Check configured agents and system health
commitbook doctor
```

Conflict handling

## Choose what happens when edits conflict

| Mode | What happens | Sync continues? |
| --- | --- | --- |
| `both` default | For .md, .markdown, and .txt files, keep both versions without markers, with this computer’s version first. Other files use manual resolution. | Yes, for text notes |
| `manual` | Leave conflict markers for you to resolve and stage. | Waits for resolution |
| `ai` | Ask the configured agent to rewrite conflicted files. | After successful resolution |
| `review` | Store an AI proposal for you to accept, edit, or reject. | Waits for approval |

Set `[conflicts] mode` in `.CommitBook/config.toml`. Binary conflicts always require manual resolution. Unresolved conflicts pause sync before the merge is pushed.

## Set up CommitBook for your notes

Install the CLI, run commitbook init in your notes repository, then run commitbook sync to check your connection. Start scheduled syncs with commitbook start.

[Get the install command](#install-3) [Read the docs](https://github.com/CommitBook/CommitBook-Core/blob/main/docs/README.md)