Work in a local copy

Clone what you can read into an ordinary git repository, work with your own editor and agents, and publish with one command.

Audience

Data teams

Prerequisites

The Kater CLI, signed in with kater login
git

A local copy puts Kater’s content on your machine as an ordinary git repository. Edit it with your own editor, search it with your own tools, and run Claude Code or Codex on it. When you are done, one command publishes your commits.

When to use this

If you want to…	Do this
Change many files at once, or use your editor’s search and replace	Work in a local copy
Run a local agent on the files	`kater agent` in a local copy
Make a small edit	Use Files in the portal, or ask your agent

Make and use a local copy

Clone.

Run kater git clone. It makes a folder named kater, or the folder you name. The folder must be new or empty.
Terminal window
```
kater git clone ~/kater
cd ~/kater
```
Work with plain git.

Edit files, then commit them. Every kater git subcommand except clone, pull and push runs git unchanged, so kater git status and git status do the same thing.
Terminal window
```
git add connections/snowflake_prod_connection/workspaces/ad_reporting
git commit -m "Add cost per conversion to spend_by_platform"
```
Pull.

kater git pull takes a new snapshot of what you can read and merges it into your branch.
Push.

kater git push publishes your commits since the last snapshot as one all-or-nothing change. -m describes it. Without -m, Kater uses your commit subjects.
Terminal window
```
kater git push -m "Cost per conversion by platform"
```

How it works

One snapshot, not the store’s history. A clone holds one snapshot commit of everything you can read. The store’s own history is never sent, because it would show paths you cannot read.
A hidden ref. The latest snapshot sits on refs/kater/upstream, and .git/kater.json records which Kater it came from. Leave both as they are.
Real merges. A pull runs a real git merge, so conflicts are ordinary git conflicts that you resolve with ordinary git tools.
All or nothing. A push sends each file with the version it had in your snapshot. If any of them changed in Kater since, nothing is applied.
One commit by you. A successful push becomes one commit in the content store, authored by you. Your copy records the new snapshot, so you keep working without cloning again.
Only commits publish. Uncommitted changes are never published.
Access follows you. A path you lose access to leaves your copy at the next pull, and Kater refuses writes to it. A reference to something you cannot read stays unresolved.
Files you can only view are marked. Each clone and pull writes .git/kater-view-only.json, the folders and files you can read and not change. The VS Code extension opens them read-only, with a lock on the tab and in the Explorer.
Renames go through Kater. A rename changes every place that names a field or an object, in every folder, so run it with kater rename. A push that takes away a name other files read, or moves a file or a folder whose path holds an object’s name, publishes nothing and prints the kater rename line that does it.
Changes that Kater makes come in by themselves. A rename, a delete, a retire, a restore, a fix in the Trash, an undo, and a change to a project, a workflow or a timeline happen in Kater. In your copy, the command then pulls the change, as kater git pull does, before it answers, and says whether your copy has it. The Kater MCP of your copy does the same, so your agent reads the change next.
Old names keep working. Each pull also writes .git/kater-retired.json, the names that renames retired, so a command in your copy finds a query, a chart, a workspace or a field by a name it had, and what is in the Trash, so a check of your copy says that a name was deleted.

If something looks wrong

Message	What to do
Nothing was published: these files changed in Kater since your last pull	Kater pulls for you. Resolve any conflicts, `git add` and `git commit` them, then run `kater git push` again.
Your branch does not include Kater’s latest content. Run kater git pull first.	Run `kater git pull`, then push again.
Nothing was published. You can view these files, not change them:	The message names each file and who can change it. Take your commits to them back with the `git checkout refs/kater/upstream -- … && git commit` line it prints, then push again. To change them, ask that person for Editor access. See Files and access.
Nothing was published. Only a rename changes a name that other files read	Take the change back with git, push again, then run the `kater rename` line the message prints.
Your local copy does not have the change. You changed these files and did not commit them	Kater made the change, and your copy did not take it, so your edits stay as they are. Commit them, then run `kater git pull`.
Your local copy does not have the change. It changes the same lines as your commits	Run `kater git pull`, and resolve the conflicts in the files the message names.
Finish the merge first	Resolve the conflicts, `git add` them and `git commit`, then push. Or run `git merge --abort`.
Uncommitted changes are not published	Commit them and push again to include them.
Nothing to publish: you have no commits since the last pull.	Commit your changes first.
This folder is not a local copy of Kater’s content.	Run the command inside your local copy, or run `kater git clone`.

Use it with agents and editors

Run kater agent claude or kater agent codex at the root of your local copy. It writes the MCP settings for that folder only, then starts the agent with Kater’s tools on the model-table skill. For Claude Code it writes .mcp.json:

{
  "mcpServers": {
    "kater": {
      "command": "kater",
      "args": ["serve", "--kater-root", "."]
    }
  }
}

For Codex it adds [mcp_servers.kater] to .codex/config.toml. Open the same folder in VS Code to use the Kater extension.

Check it worked

git log shows a “Kater snapshot” commit after a clone or pull.
kater git push says “Published 1 change to Kater.” or the number you published.
Your change shows in the portal, in the object’s History, under your name.

Next steps

Check a query from the terminal, change a query and build it and test a shared model, the three command-line workflows
VS Code extension
Content store and GitHub write-back