Configuration

Everything lives in <project>/.tomo/config.toml. The file is optional; with no file you get the defaults. There's no global config.

Path rules and classes #

Every path in the tree is classified into exactly one of three classes:

You assign classes with [[rules]] entries — git-style glob patterns, matched against the path relative to the project root:

# History capture: adaptive (default) | every-change | off | { interval_ms = 5000 }
[history]
mode = "adaptive"

[[rules]]
pattern = "target/"           # trailing slash expands to target/**
class = "ignored"

[[rules]]
pattern = "dist/**"
class = "synced+unversioned"
direction = "pull"            # both (default) | push | pull

Glob semantics #

• * and ? never cross a / (they match within one path component).
• ** matches across directory boundaries — target/**, **/*.log.
• A pattern without a / is still root-anchored: *.log matches only top-level logs; use **/*.log to match in every directory.
• A trailing slash auto-expands: target/ is treated as target/**.

Last matching rule wins #

When several rules match a path, the last one in the file wins (git-style precedence). This lets a narrow later rule carve an exception out of a broad earlier one:

[[rules]]
pattern = "build/**"
class = "ignored"

[[rules]]
pattern = "build/keep/**"     # re-include one subtree
class = "synced+versioned"

Built-in default ignores #

Unless you turn them off, Tomo prepends a small set of built-in ignored rules for editor/tool churn, OS metadata, database sidecars, git metadata, and large regenerable dependency/cache trees. They are applied before your rules, so (last match wins) any [[rules]] entry for the same glob overrides a default. This is the complete current list:

The .git defaults cover the root repo, nested repos, and submodules — .git is a directory in an ordinary clone but a file in a worktree or submodule, so the bare **/.git matches both forms. Syncing .git would cross-contaminate two independent repositories' objects and index; two .git trees must ignore each other entirely. Lookalikes like .gitignore, .gitattributes, and .gitkeep are not matched and sync normally. The .db/.sqlite journal patterns are anchored to those two stems on purpose — a bare *-journal would wrongly swallow an ordinary file like travel-journal.

The dependency and cache trees — node_modules, Python virtualenvs (.venv/venv) and tool caches (__pycache__, .pytest_cache, .mypy_cache, .ruff_cache), and Terraform's .terraform — are each ignored as a directory and its contents, following the same two-pattern shape as .git. They share one rationale: they're large, machine-regenerable, and frequently platform-specific (native node_modules addons, absolute-path virtualenvs, Terraform provider binaries), so dragging them across a Mac↔Linux pair is wasted bytes at best and broken on the peer at worst. Only whole path components match, so a directory merely named like a default — node_modules_backup, my.venv — syncs normally.

IDE and editor project dirs — .idea, .vscode, .vs, .fleet, .zed, and Sublime's per-user *.sublime-workspace — are ignored by default too. They mix shareable settings with machine-local state (indexes, caches, absolute SDK paths) that churns constantly and is plain wrong on the other machine — a synced .idea/ happily points your Linux box at your Mac's JDK. If your team checks .vscode into the repo, git already carries the shared copy; want tomo to sync it anyway? Re-include it with the two-rule pair below. (*.sublime-project, the shareable half of Sublime's pair, stays synced.)

Web-framework dev caches — .next, .nuxt, .svelte-kit, .astro, .angular, .turbo, .parcel-cache, .expo, .vite, .docusaurus, and the generic .cache — are each a dev server's or CLI's regenerable scratch dir: machine-local, disposable, and often platform- or absolute-path-specific, so they never help the peer. They're ignored as a directory and its contents, like the trees above, and every one is overridable. These are dev-server state, not deploy artifacts — the build-output decision below is unchanged. (.cache is dot-prefixed so collisions are unlikely, and its bare glob matches a lone file named .cache as well as the directory, which is intended.)

Disable the whole set with:

[sync]
default_ignores = false       # ON by default

Re-including an ignored tree takes two rules #

Because the scan won't descend into an ignored directory, un-ignoring a whole tree needs two rules — one for the directory itself, one for its contents — exactly like git:

[[rules]]
pattern = ".git"              # un-ignore the directory itself…
class = "synced+versioned"

[[rules]]
pattern = ".git/**"           # …and everything under it
class = "synced+versioned"

What you cannot reconfigure #

.tomo/** is always ignored, enforced below the rule engine as a constant — no rule, however hostile, can make Tomo watch, sync, or version its own state directory. Only the first path component counts, so a nested a/.tomo in your own tree is an ordinary path.

That directory also holds a generated .tomo/README.md — a short brief for any coding agent working in the tree, explaining that files can change under it in real time (a peer's edits land in milliseconds) and that every save is recoverable with tomo log / tomo restore. Because .tomo/** never syncs, each machine writes its own copy; Tomo regenerates it but never touches your CLAUDE.md/AGENTS.md. Who's on the other end lives in .tomo/state/status.json (or tomo status --json).

History modes #

The [history] section chooses how often a save becomes a version:

The remote peer #

tomo connect and the first tomo sync write the [remote] section for you. You can also write it by hand:

[remote]
host = "you@gpu-box"          # SSH target (resolved through ~/.ssh/config)
path = "/home/you/proj"       # the peer's project-root path
identity = "~/.ssh/gpu_ed25519"  # optional explicit key (else agent / config / defaults)

SSH config support #

The target you give is resolved through ~/.ssh/config first, exactly as your own ssh would — so Tomo authenticates and connects wherever ssh host already works, including hosts reachable only through a jump host or with a non-default key. Point Tomo at a different file with TOMO_SSH_CONFIG. Supported directives:

Unknown keywords are ignored (their names collected for a debug line).

Authentication order #

Keys are tried in this order, first accepted wins: ssh-agent (unless IdentitiesOnly yes) → the [remote] identity you recorded → the IdentityFiles from ~/.ssh/config → the built-in ~/.ssh/id_ed25519 / id_rsa. Encrypted (passphrase) keys are out of scope for v0.

Known-hosts semantics #

• Lookup spans every user known-hosts file and the global set (OpenSSH parity). Recording (under accept-new) targets only the first writable user file — never the global set, never /dev/null.
• StrictHostKeyChecking no accepts any key unpinned; accept-new records an unknown key but rejects a changed one with the usual MITM error; yes/default keeps strict behavior.
• Port-form fallback: for a non-default port the [host]:port form is tried first, then — matching OpenSSH's "found matching key w/out port" compatibility — the plain port-less host form of the same files. A port-form match/mismatch always wins; a plain-form match connects and logs a compat note. Recording always uses the port-qualified form.
• Before negotiating, Tomo scans those files for the key types already recorded and biases the host-key-algorithm order toward them (as OpenSSH does), so a host recorded only under, say, ECDSA isn't wrongly reported "not found".

Environment variables #

--json output is always byte-identical regardless of these — styling never leaks into machine-readable surfaces.

Troubleshooting #