codemcp

1NOTICE: claude code is available with Anthropic's $20/mo subscription, so I consider
2codemcp fully obsolete.  However, there are some good design ideas (especially around
3the Git-versioning scheme) that I eventually want to port into the current generation
4of agentic coding clis.
5 
6# codemcp
7 
8Make Claude Desktop a pair programming assistant by installing codemcp.  With
9it, you can directly ask Claude to implement features, fix bugs and do
10refactors on a codebase on your computer; Claude will directly edit files and
11run tests.  Say goodbye to copying code in and out of Claude's chat window!
12 
13![Screenshot of Claude Desktop with codemcp](static/screenshot.png?raw=true)
14 
15codemcp offers similar functionality to other AI coding software (Claude Code,
16Cursor, Cline, Aider), but it occupies a unique point in the design space:
17 
181. It's intended to be used with **Claude Pro**, Anthropic's $20/mo
19   subscription offering.  I like paying for my usage with a subscription plan
20   because it means **zero marginal cost** for agent actions; no more feeling
21   bad that you wasted five bucks on a changeset that doesn't work.
22 
23   Note that if you have Claude Max ($100/mo), Claude Code can also be used
24   with subscription based pricing.  The value proposition for codemcp is
25   murkier in this case (and it is definitely inferior to Claude Code in some
26   respects), but you can still use codemcp with Claude Max if you prefer some
27   of the other UI decisions it makes.  (Also, it's open source, so you can
28   change it if you don't like it, unlike Claude Code!)
29 
302. It's built around **auto-accept by default**.  I want my agent to get as
31   far as it can without my supervision, so I can review everything in one go at
32   the end.  There are two key things that codemcp does differently than most
33   coding agents: we **forbid unrestricted shell**, instead requiring you to
34   predeclare commands the agent can use in ``codemcp.toml``, and we **Git
35   version all LLM edits**, so you can roll back agent changes on a
36   fine-grained basis and don't have to worry about forgetting to commit
37   changes.
38 
393. It's **IDE agnostic**: you ask Claude to make changes, it makes them, and
40   then you can use your favorite IDE setup to review the changes and make
41   further edits.  I use vim as my daily driver editor, and coding environments
42   that require VSCode or a specific editor are a turn off for me.
43 
44## IMPORTANT: For master users - Major changes for token efficiency
45 
46To improve codemcp's token efficiency, on master I am in the process of
47changing codemcp back into a multi-tool tool (instead of a single tool whose
48instructions are blatted into chat when you InitProject).  This means you have
49to manually approve tool use.  Because tool use approval is persistent across
50multiple chats, I think this is a reasonable tradeoff to make, but if you
51really don't like, file a bug at
52[refined-claude](https://github.com/ezyang/refined-claude/issues) browser
53extension for supporting auto-approve tool use.
54 
55## Installation
56 
57I recommend this specific way of installing and using codemcp:
58 
591. Install `uv` and install git, if they are not installed already.
60 
612. Install [claude-mcp](https://chromewebstore.google.com/detail/mcp-for-claudeai/jbdhaamjibfahpekpnjeikanebpdpfpb) on your browser.
62   This enables you to connect to SSE MCP servers directly from the website,
63   which means you don't need to use Claude Desktop and can easily have
64   multiple chat windows going in parallel.  We expect this extension should
65   be soon obsoleted by the rollout of
66   [Integrations](https://www.anthropic.com/news/integrations).  At time of
67   writing, however, Integrations have not yet arrived for Claude Pro subscribers.
68 
693. Run codemcp using ``uvx --from git+https://github.com/ezyang/codemcp@prod codemcp serve``.
70   You can add ``--port 1234`` if you need it to listen on a non-standard port.
71 
72   Pro tip: if you like to live dangerously, you can change `prod` to `main`.  If
73   you want to pin to a specific release, replace it with `0.3.0` or similar.
74 
75   Pro tip: you can run codemcp remotely!  If you use
76   [Tailscale](https://tailscale.com/) and trust all devices on your Tailnet,
77   you can do this securely by passing ``--host 100.101.102.103`` (replace the
78   IP with the Tailscale IP address of your node.  This IP typically lives in
79   the 100.64.0.0/10 range.)  **WARNING:** Anyone with access to this MCP can perform
80   arbitrary code execution on your computer, it is **EXTREMELY** unlikely you want to
81   bind to 0.0.0.0.
82 
834. Configure claude-mcp with URL: ``http://127.0.0.1:8000/sse`` (replace the port if needed.)
84 
855. Unfortunately, the web UI inconsistently displays the hammer icon.  However, you can verify
86   that the MCP server is working by looking for "[MCP codemcp] SSE connection opened" in the
87   Console, or by asking Claude what tools it has available (it should say
88   tools from codemcp are available.)
89 
90If you prefer to use Claude Desktop or have unusual needs, check out [INSTALL.md](INSTALL.md) for
91installation instructions for a variety of non-standard situations.
92 
93## Usage
94 
95First, you must create a `codemcp.toml` file in the Git repository checkout
96you want to work on.  If you want the agent to be able to do things like run
97your formatter or run tests, add the commands to execute them in the commands
98section (note: these commands need to appropriately setup any virtual
99environment they need):
100 
101```toml
102format = ["./run_format.sh"]
103test = ["./run_test.sh"]
104```
105 
106The ``format`` command is special; it is always run after every file edit.
107 
108Next, in Claude Desktop, we recommend creating a Project and putting this in
109the Project Instructions:
110 
111```
112Initialize codemcp with $PROJECT_DIR
113```
114 
115Where `$PROJECT_DIR` is the path to the project you want to work on.
116 
117Then chat with Claude about what changes you want to make to the project.
118Every time codemcp makes a change to your code, it will generate a commit.
119 
120To see some sample transcripts using this tool, check out:
121 
122- [Implement a new feature](https://claude.ai/share/a229d291-6800-4cb8-a0df-896a47602ca0)
123- [Fix failing tests](https://claude.ai/share/2b7161ef-5683-4261-ad45-fabc3708f950)
124- [Do a refactor](https://claude.ai/share/f005b43c-a657-43e5-ad9f-4714a5cd746f)
125 
126codemcp will generate a commit per chat and amend it as it is working on your feature.
127 
128## Philosophy
129 
130- When you get rate limited, take the time to do something else (review
131  Claude's code, review someone else's code, make plans, do some meetings)
132 
133- This is *not* an autonomous agent.  At minimum, you have to intervene after
134  every chat to review the changes and request the next change.  While you
135  *can* ask for a long list of things to be done in a single chat, you will
136  likely hit Claude Desktop's output limit and have to manually "continue" the
137  agent anyway.  Embrace it, and use the interruptions to make sure Claude is
138  doing the right thing.
139 
140- When Claude goes off the rails, it costs you time rather than dollars.
141  Behave accordingly: if time is the bottleneck, watch Claude's incremental
142  output carefully.
143 
144## Configuration
145 
146Here are all the config options supported by `codemcp.toml`:
147 
148```toml
149project_prompt = """
150Before beginning work on this feature, write a short haiku.  Do this only once.
151"""
152 
153[commands]
154format = ["./run_format.sh"]
155test = ["./run_test.sh"]
156```
157 
158The `project_prompt` will be loaded when you initialize the project in chats.
159 
160The `commands` section allows you to configure commands for specific tools.  The
161names are told to the LLM, who will decide when it wants to run them.  You can add
162instructions how to use tools in the `project_prompt`; we also support a more verbose
163syntax where you can give specific instructions on a tool-by-tool basis:
164 
165```
166[commands.test]
167command = ["./run_test.sh"]
168doc = "Accepts a pytest-style test selector as an argument to run a specific test."
169```
170 
171## Troubleshooting
172 
173To run the server with inspector, use:
174 
175```
176PYTHONPATH=. mcp dev codemcp/__main__.py
177```
178 
179Logs are written to `~/.codemcp/codemcp.log`. The log level can be set in a global configuration file at `~/.codemcprc`:
180 
181```toml
182[logger]
183verbosity = "INFO"  # Can be DEBUG, INFO, WARNING, ERROR, or CRITICAL
184```
185 
186Logging is not configurable on a per project basis, but this shouldn't matter
187much because it's difficult to use Claude Desktop in parallel on multiple
188projects anyway.
189 
190## Contributing
191 
192See [CONTRIBUTING.md](CONTRIBUTING.md).
193