Skip to content

AI sessions

Use Milestone from the terminal

Updated July 25, 2026

You can connect Milestone to claude or codex running in a plain terminal, without the desktop app. You add a small connection file to each repository, and sessions there get Milestone's tools.

Terminal-only setup has one real limit

Automatic recall - your team's context arriving on every prompt - needs the desktop app. Without it your agent still has Milestone's tools and will use them when asked or when it decides to, but sessions don't start pre-loaded. See Team knowledge sync.

The idea

One repository, one workspace. Your workspace is baked into the token, so instead of switching a global setting, you drop a connection file in each repo. The folder you're in decides which workspace you're talking to.

Connect Claude Code

1

Generate a token

In the web app, switch to the workspace you want this repo connected to, open Context → Setup, and click Generate Token.

2

Create .mcp.json in your repo root

Add a file named .mcp.json next to your package.json or README:

{
  "mcpServers": {
    "milestone": {
      "type": "http",
      "url": "https://mcp.milestone-app.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN_HERE"
      }
    }
  }
}
3

Keep the token private

The token is a long-lived secret. Add .mcp.json to your .gitignore before you commit anything.

4

Open Claude Code there

Run claude from that folder. It picks up .mcp.json automatically and may ask you to approve the milestone server once.

Connect Codex

Codex reads a single global config instead of a per-repo file. Add this to ~/.codex/config.toml:

[mcp_servers.milestone]
url = "https://mcp.milestone-app.com/mcp"

[mcp_servers.milestone.http_headers]
Authorization = "Bearer YOUR_TOKEN_HERE"

The token has to go under http_headers - Codex won't accept it inline.

Verify it worked

In a session, ask your agent to search your team's knowledge for something only your team would know. If it comes back with your workspace's answer, you're connected.

If something's wrong

  • Wrong workspace's answers - the token came from a different workspace. Generate a new one from the right workspace and replace it.
  • Changes didn't take effect - a running session reads its config once at startup. Quit and reopen it.
  • Stopped working - tokens can be revoked. Generate a fresh one.

Related

Ready to try Milestone?

Give your team and its AI agents one shared memory.

Request early access