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.
Requires Homebrew on macOS or Linux.
Install on each computer, then set up your notes repository.
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
-
Install with Homebrew
Install the CLI on each computer where you keep your notes.
terminalbrew install commitbook/tap/commitbook -
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.
terminalcd ~/my-notes commitbook init -
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.
terminalcommitbook sync commitbook schedule 1h commitbook start -
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. -
Check sync status
Run commitbook status from the repository to inspect local changes, remote sync state, and scheduler health.
terminalcommitbook 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.
Laptop
Local notes + CommitBook
↔ Git remote ↔
Shared repository
Desktop
Local notes + CommitBook
$ 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.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.
# Hourly; equivalent to 0 * * * *
commitbook schedule 1h
commitbook start
# Pause scheduled syncs
commitbook stopAI, 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[commit]
mode = "timestamp"
# → Writing 2026-09-27 14:30:02AI · opt-in
agent-written[commit]
mode = "ai"
agent = "claude"
# → Summarize sync UX notes;
# tighten schedule copyAI 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.
agent = "any" tries installed agents in the order shown until one succeeds, then falls back to a timestamp if none succeeds.
# Check configured agents and system health
commitbook doctorConflict 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.