DEV Community

tdk-cli
tdk-cli

Posted on

Claude Can Do WHAT?! Start Your Whole Local Stack From a Chat

You can ask Claude to start your whole local stack. It can check that Docker is ready, bring up the services, wait until they are healthy, and read the logs when one fails. You type one sentence. Claude runs the commands.

That works because TDK CLI ships a Model Context Protocol (MCP) server. Claude calls its tools instead of guessing at shell output.

What Claude actually gets

Run tdk mcp and TDK exposes six tools:

  • doctor checks the host, including whether a container runtime is reachable and whether tdk up can work here.
  • up starts the stack. It returns straight away, because a build can take longer than one tool call.
  • status reports readiness, ports, and URLs.
  • logs returns a bounded snapshot of recent lines for a service.
  • down stops the stack.
  • resource_list lists the services in the project.

These are not wrappers around free text. Each one runs the matching --json command, so Claude gets structured results it can check.

Set it up

You need the CLI and Docker. Install the CLI:

npm install -g @tdk-landscape/tdk-cli-core
tdk --version
Enter fullscreen mode Exit fullscreen mode

Then connect your client. For Codex, add a project-scoped entry to .codex/config.toml:

[mcp_servers.tdk]
command = "tdk"
args = ["mcp"]
cwd = "/absolute/path/to/your/tdk-project"
Enter fullscreen mode Exit fullscreen mode

For Claude Code, follow the Claude Code section of the TDK agent tooling guide. The principle is the same: run tdk mcp from the project directory.

The cwd matters. The server looks for .tdk/project.json, and if it starts in the wrong folder, it cannot find your project.

Ask for outcomes

Plain requests work best, because they describe the result you want:

  • "Check whether this machine can run the stack, and tell me what to fix if not."
  • "Start the API and the worker, and tell me when they are ready."
  • "The API looks broken. Show me the last five minutes of its logs."
  • "Stop everything."

For the first request, Claude calls doctor. The result includes canUp. If that is false, Claude stops and explains why, instead of retrying.

Watch it work

Here is what a good session looks like, step by step:

  1. Claude calls doctor. Docker is reachable, so canUp is true.
  2. Claude calls up for the API and the worker. TDK starts them and their dependencies.
  3. Claude calls status again and again until readiness.ready is true.
  4. If one service fails, Claude calls logs for that service only, with a small tail, and quotes the error line.

That loop has a clear end: the readiness check. Claude does not have to decide by feel whether the stack is up.

The part people miss

up does not wait. It starts Tilt in the background and returns, so the agent must poll status. This is deliberate. A slow image build should not make a tool call time out.

Logs are snapshots. There is no streaming tool, so Claude reads the recent lines, decides, and asks again if it needs more.

The server runs locally over stdio. There is no hosted endpoint and no network port to expose. Keep it that way.

Know the limits

  • Claude cannot start Docker for you. If the host has no container runtime, doctor will say so, and that is the end of the local stack on that machine.
  • A WebContainer has no Docker daemon, so canUp is false there.
  • Stopping a stack is low-risk. Deleting data, resetting volumes, or touching production configuration is not. Keep those with a person.
  • TDK is for local development. Deployment stays with Helm, Argo CD, or Kustomize.

Try it

Pick a project with two services and a database. Connect Claude, then ask it to bring the stack up and tell you when it is ready. Watch it call doctor, up, and status in order. The first time it works end to end, you will understand why this is worth the five minutes of setup.

Top comments (0)