The CLI

The sidecar

The sidecar is the part of Knwlge that runs on your machine: a small background service your AI coding agent talks to. You install it once, and afterwards mostly forget it — this page is for when you do not.

What the sidecar is

A Node.js process that listens on 127.0.0.1 only, started by your operating system when you log in. It does the work behind every prompt:

• Briefs. Your agent's prompt hook hands it each prompt; it works out the folder's project and asks that project's Enterprise Server for context, within 1.5 seconds.
• Session capture and learning. At the end of each turn it captures what the organization's policy allows, redacted on your machine, and may ask the agent to record what it learned (Session capture and learning).
• Upkeep. It keeps each project's repository list fresh (every six hours), reports usage counts to Knwlge Global every ten minutes for your Dashboard, and runs the background upkeep of the team's documents.

Your agent's tools — context.search, knowledge.lookup and the rest — do not go through the service: the MCP entry install wrote starts knwlge sidecar mcp-stdio for each agent session, which talks to the project's server itself. So when the service is down, tools still work but prompts arrive without a brief.

Run it as a service

knwlge sidecar start installs the sidecar as a service for your user, starts it, and waits until it answers. Run it again whenever you like: it reconciles what is installed with this copy of the CLI and changes nothing that is already right.

knwlge sidecar start

$ knwlge sidecar start
  ██   ▄█▀   Knwlge CLI v1.0.0
   █▄▄█▀     ● signed in as ada@acme.example · project Acme Platform
   █▀▀█▄     ~/.team-context-gateway · node v22.20.0 · darwin arm64  ·  Docs https://knwlge.com/docs
  ██   ▀█▄   Give your agent the context it's been missing.

───────────────────────────────────────────────────────────────────────────────

{
  "command": "sidecar service-install",
  "changed": true,
  "plan": { … },
  "activation": {
    "attempted": true,
    "activated": true,
    "healthUrl": "http://127.0.0.1:32770/healthz",
    "healthOk": true,
    "commands": [ … ]
  }
}

It listens on 127.0.0.1:32770; pass --port to choose another. The service runs the exact Node binary and CLI copy you ran the command with, so re-run sidecar start after moving to a new Node installation. If the new service does not come up healthy, the one that was there before is put back.

Run it in the foreground

For a first look, or to watch it while you debug, run it in your terminal instead. It prints where it listens and stays until you press Ctrl+C. It is a separate process from the service, on a port of its own.

knwlge sidecar start --foreground

$ knwlge sidecar start --foreground
{
  "command": "sidecar start",
  "status": { … },
  "baseUrl": "http://127.0.0.1:53817",
  "healthUrl": "http://127.0.0.1:53817/healthz",
  "httpMcpEnabled": false,
  "tokenStorage": "macos-keychain"
}

Check that it is running

The quickest look is the control panel: run knwlge and the line under Projects says ● sidecar running · pid … · 127.0.0.1:32770, with each AI client's hook beside it. From a script:

knwlge doctor --repo-root "$PWD"     # the whole install, end to end
knwlge sidecar status                # what the sidecar and your session report, as JSON

Or ask the operating system:

# macOS
launchctl print gui/$UID/com.team-context-gateway.sidecar
# Linux
systemctl --user status team-context-gateway.service

Restart, stop and remove it

Switches

The sidecar reads a few environment variables when it starts. The service sidecar start installs does not read your shell's environment, so these apply to a sidecar started with them — in the foreground, say. To stop capture for good, opt out in your server's console instead (Turning it off).

Switching copies of the CLI

The hooks, MCP entries and service run one exact copy of the CLI. A different copy — a build you want to try, a new release in another place — refuses to overwrite that wiring, with a message such as Refusing to overwrite a modified claude_code Team Context Gateway hook. It was written by another knwlge copy. Run reinstall from the copy that should take over:

knwlge reinstall --dry-run    # each file it would change, old launcher → new
knwlge reinstall

It rewrites only entries in the exact shape the installer writes, keeps your other hooks and settings, backs up every file it changes, moves the service over and health-checks it — and puts everything back if the new service does not come up. You stay signed in. Anything it does not recognise stops it before it changes anything, naming the file to look at. Restart open agent sessions afterwards.

Troubleshooting

When in doubt, knwlge doctor --repair --repo-root "$PWD"Copy to clipboard checks the install end to end and fixes what it safely can.