Skip to main content

Run your first local session

In this tutorial, you will start mecatui in a local project and ask Mecatl to inspect it. mecatui runs a private embedded server, so you do not need to start a separate service.

Prerequisites​

You need:

  • macOS or Linux with Homebrew;
  • an API key for Anthropic, OpenAI, or OpenRouter; and
  • a local project directory that you trust.

The project is your workspace. Mecatl limits its file tools and commands to this directory.

Install Mecatl​

Homebrew installs the mecatui client and the mecated server:

brew install stacklok/tap/mecatl
mecatui --version

The version command should print a release tag. For signed archives and source builds, see Install Mecatl.

Start mecatui​

Mecatl detects the provider from its environment variable. Set one of ANTHROPIC_API_KEY, OPENAI_API_KEY, or OPENROUTER_API_KEY in the shell where you will run mecatui:

cd <PROJECT_DIRECTORY>
export <PROVIDER_API_KEY>="<API_KEY>"
mecatui --workspace "$PWD"

Replace <PROVIDER_API_KEY> with the variable for your provider.

The welcome screen shows your workspace and active model. To use a different model, enter /models, select one, and press enter. A small, low-cost model is enough for this tutorial.

The header also shows mode default, identifying the active permission mode. With the default permission policy, read-only tools can run without approval and actions that change the workspace ask first.

Inspect the project​

Enter this request:

Inspect the top-level files and explain what this project does. Cite the files you used.

You should see tool cards as Mecatl reads the workspace, followed by an answer based on your project. Press ctrl+t on a tool card to inspect its full input and result.

You now have a local session: the conversation, selected model, workspace, and tool history that Mecatl keeps together. Exit with ctrl+c twice or /quit. To continue the newest stored session, run:

mecatui --workspace "$PWD" --resume-latest

Add tools from local MCP servers (optional)​

MCP servers give agents tools for working with external services and data. ToolHive is Stacklok's open source runtime for running MCP servers locally.

If ToolHive has MCP servers running in its default group, the embedded server discovers them at startup. Enter /mcp to inspect the available MCP sources and tools. Mecatl connects to those servers but does not start them.

Next steps​