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 Anthropic API key; and
  • a local project directory that you trust.

The project is your workspace. Mecatl uses it as the root for file tools and as the starting directory for commands. Shell access follows the configured permission policy; a workspace alone does not provide OS isolation.

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 Conda-forge, release archives, verification, and source builds, see Install mecatui.

Start mecatui​

This tutorial uses Anthropic. Set your API key in the terminal where you will run mecatui, then start the client in your project:

cd <PROJECT_DIRECTORY>
export ANTHROPIC_API_KEY="<ANTHROPIC_API_KEY>"
mecatui --workspace "$PWD" --default-provider anthropic

For another provider or guided credential setup, follow local provider setup before returning to this step.

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

Next steps​