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 from Anthropic, OpenAI, OpenRouter, or OpenCode; 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.

Set up a provider​

Use an API key for this tutorial. Run the interactive setup and select your provider:

mecatui providers setup

Enter the API key when prompted. mecatui saves locally managed credentials without displaying them. You can check the configured provider later with mecatui providers status.

For custom providers and gateways that use API keys or OIDC, see Use mecatui.

Start mecatui​

cd <PROJECT_DIRECTORY>
mecatui

To submit the first prompt at startup while keeping the session interactive, pass --prompt:

mecatui --prompt "Summarize the failing tests in this repository"

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 --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​