CodeMesh from the terminal

The short answer

npm install -g @codemesh-app/cli, then codemesh login, codemesh sync, codemesh connect. That is the whole setup. It needs Node 18.17 or newer and no editor at all, and it shares one account and one graph with the VS Code extension: signing in with either signs in both.

Install

terminal

npm install -g @codemesh-app/cli

This puts two commands on your PATH: codemesh, and codemesh-sync for the background daemon. The git hooks look for the second one by name, so it has to be there. The daemon and the engine binary ship as per-platform optional dependencies, the same pattern esbuild and swc use, so npm downloads only the one for your machine.

Use the scoped name

The package is @codemesh-app/cli. An unscoped npm install -g codemesh installs a different, unrelated package that is not ours.

If the install fails with EACCES

Your npm was installed system wide, so its global prefix is a root owned directory and no -g install can write there. This is not specific to CodeMesh; every global package fails the same way. Point npm at a directory you own:

terminal

npm config set prefix ~/.local
npm install -g @codemesh-app/cli

Then make sure ~/.local/bin is on your PATH. Do not reach for sudo npm install -g: it works once and leaves root owned files in ~/.npm, which breaks later installs that have nothing to do with CodeMesh. A version manager such as nvm, fnm or volta avoids the problem entirely.

Quick start

terminal

codemesh login            # sign in or create an account, in your browser
cd ~/your/repo
codemesh sync             # register this repo and run the first ingest
codemesh connect          # wire up every AI agent on this machine

After connect, ask your agent something about the repository. It reaches the graph over MCP and gets back the few spans that answer the question, with a file and a line, instead of reading whole files.

Signing in

terminal

codemesh login                 # browser sign in, OAuth 2.1 with PKCE
codemesh login --no-browser    # prints the URL instead of opening one
codemesh status                # gateway, credential, org, plan, graph readiness
codemesh logout                # pause syncing and stop the daemon

Technical note

On a headless box or over SSH, codemesh login --no-browser prints the URL for you to open somewhere else. There is no API key environment variable for the CLI: the credential is written once to ~/.codemesh/credentials.json at mode 0600 and rotated by the daemon.

Repositories and syncing

terminal

codemesh sync                  # the repo containing the working directory
codemesh sync ~/a ~/b          # specific repos
codemesh sync --here           # every repo directly below this folder
codemesh sync --init           # git init any folder here that is not a repo yet
codemesh sync --watch          # supervision loop, every 30s
codemesh catchup               # ingest what changed while you were away

terminal

codemesh repos                 # registered on this machine
codemesh repos --all           # every repo your organization has
codemesh repos add owner/name  # clone and register one you do not have
codemesh repo disable [path]   # stop syncing, keep the data
codemesh repo enable  [path]   # resume syncing
codemesh repo delete-data      # schedule permanent deletion of its graph

Syncing needs no configuration. Signing in and running sync once is enough; the daemon keeps the graph in step from then on. codemesh status --watchrepaints a live table every five seconds if you want to watch it work.

Connecting agents

terminal

codemesh connect                       # every detected agent
codemesh connect claude-code           # just one
codemesh connect claude-code --take-over  # claim one the editor manages
codemesh agents                        # installed, connected, needs reconnect
codemesh disconnect claude-code        # give the claim back
codemesh info                          # raw endpoints, for any other MCP client

Asking the graph directly

You do not need an agent in the loop. These go straight to the engine and print what an agent would have received.

terminal

codemesh ontology                          # how the graph is laid out, read this first
codemesh context "where is the retry budget set"
codemesh answer  "how does auth work"      # a finished, cited answer
codemesh search  "MAX_ATTEMPTS"            # exact text or symbol
codemesh query   "<cypher>"                # structural query over the graph

Command reference

Command	What it does
login, logout, status	Sign in, sign out, and what state this machine is in
sync, catchup	Register repositories and ingest them, or catch up after time away
repos, repo	List repositories, enable, disable, add or delete a repository's data
connect, disconnect, agents	Wire agents to the graph, release them, see their state
info	Raw MCP endpoints for a client the table does not cover
context, answer, search, query, ontology	Ask the graph directly, without an agent
plan, chat	The plan and conversation memory subgraphs
usage, activity, graph, models	Tokens, cost and time; what the graph holds; per agent models
scope	What an agent is allowed to read
guard	The tool guard that keeps agents off raw file reads
doctor	What is wrong, and what to run next
support	Open and read support tickets without leaving the shell
purge	Remove CodeMesh from this machine

Where state lives

Everything is under ~/.codemesh/, shared with the VS Code extension and the daemon. Nothing is written inside your repositories except git hooks.

Path	Contents
credentials.json	The machine's one credential copy, mode 0600, rotated by the daemon
sync-repos.json	Which checkouts are registered
guard-config.json	Guard settings, re-read on every tool call
agent-owners.json	Which client manages which agent
agent-models.json	Per agent model, shared with the extension's picker
logs/daemon.log	The daemon's running trace

Environment variables

Variable	Effect
CODEMESH_API_URL	Gateway to talk to. Overrides the compiled default, overridden by --api-url
CODEMESH_SYNC_BINARY	Absolute path to a codemesh-sync you built yourself
CODEMESH_DAEMON_URL	Where to reach the daemon. Defaults to http://127.0.0.1:7077
CODEMESH_SCOPE_ROOT	Pins the scope root for a launched bridge. Set by connect

Questions

Do I need the VS Code extension as well?

No. The CLI does everything the extension does for setup. If you use both, they share one account, one credential and one graph out of ~/.codemesh/, so signing in with either signs in both.

Does it work with agents that are not in the list?

Yes. codemesh info prints the MCP endpoints, and any MCP capable client can point at them. connect is a convenience for the agents it can detect, not a restriction on which clients work.

What if something is not working?

Run codemesh doctor. It checks each part of the setup in order and prints the exact next command rather than a generic error.

How do I remove it?

codemesh logout pauses syncing and stops the daemon. codemesh purge removes CodeMesh from the machine, and codemesh repo delete-data schedules deletion of a repository's graph on the server.

Install it and ask your first question

Start Saving Tokens See the Benchmark