shai: a Rust coding agent you drive from the terminal or an HTTP API

One Rust binary with five ways to run it

shai describes itself as a coding agent, a pair programming buddy that lives in the terminal, written in Rust.

What makes it more than a chat wrapper is the number of entry points. There is an interactive coding agent you chat with in the terminal to write code, fix bugs and get answers. There is a headless mode where prompts are piped in for scripting and automation. There is an HTTP server mode that exposes OpenAI compatible APIs with SSE streaming. There is a shell assistant that suggests fixes when your commands fail. On top of that sit project context loaded from AGENTS.md files, MCP support with OAuth for specialised agents, and skills that extend the agent with on-demand procedural instructions.

The provider list is wide. It works with OVHcloud, OpenAI, Anthropic, Mistral, Ollama and OpenRouter, which means the interesting decisions are not about which vendor you can use but about which one you have a key for.

The Rust workspace structure shows where the boundaries are drawn. The Cargo.toml lists five members: shai-macros, shai-llm, shai-core, shai-cli and shai-http. The provider integration lives in its own crate, the HTTP surface in another, the CLI in another, and shai-core presumably holds what the others share. The top level of the repository matches that split with directories of the same names, alongside an install.sh, an AGENTS.md, a docs directory and configuration files such as .shai.config and .ovh.config.

The licence is Apache-2.0. The releases are recent and frequent at this stage: v0.2.2 on 2026-10-09, v0.2.1 on 2026-10-08 and v0.2.0 on 2026-10-08, with the last push on 2026-10-09. Version numbers below 1.0 mean the interface is still moving.

Installing it, and the rate limit you hit before signing in

The stable release installs with a one line script:

curl -fsSL https://raw.githubusercontent.com/ovh/shai/main/install.sh | sh

A nightly build uses the same script with a different environment variable:

curl -fsSL https://raw.githubusercontent.com/ovh/shai/main/install.sh | SHAI_RELEASE=unstable sh

Either way the shai binary lands in $HOME/.local/bin, so that directory has to be on your PATH.

Then there is the detail that catches every new user. By default shai uses OVHcloud as an anonymous user, and the consequence is stated bluntly: you will be rate limited. To sign in with your account or select another provider you run:

shai auth

The numbers behind that warning are in the configuration section. Authenticating with an API key raises the rate limit from 2 requests per minute, counted per IP and per model, to 400 requests per minute, counted per project and per model. That is a two hundredfold difference, and it is the reason to treat shai auth as part of installation rather than an optional later step.

The OVHcloud side needs a Public Cloud project and an API key generated from the AI Endpoints section of the control panel, following the OVHcloud getting started guide. The endpoint catalog is at endpoints.ai.cloud.ovh.net/catalog, and there is one piece of advice worth heeding: models with a function calling feature work best with shai, and for models without it you are told to force structured output with the /set so option. In other words, whether your provider supports tool calling decides how smoothly the agent works.

For building from source, the repository documents a clone and a release build:

git clone [email protected]:ovh/shai.git
cd shai
cargo build --release

Interactive mode, sessions and the headless pipe

The interactive mode is the default. Running shai with no arguments starts the TUI, and the documented variants cover agents and session restore:

shai                          # Start TUI
shai -a myagent              # Start TUI with a custom agent
shai session                 # Start TUI with session picker
shai session <id>            # Start TUI restoring a specific session
shai session latest          # Start TUI restoring the most recent session
shai -r <session-id>        # Restore a session by ID
shai --latest                # Restore the most recent session

Session handling is prominent, with four different ways to reach the same thing, which tells you resuming conversations is a normal part of the workflow rather than an afterthought.

The headless mode is the one that makes shai usable in a script. Instead of the TUI you pass a prompt with -p, or pipe it in on standard input:

shai -p "make me a hello world in main.py"
echo "make me a hello world in main.py" | shai

And you can chain calls, which is where the agent starts to look like a pipeline rather than a chat:

echo "make me a hello world in main.py" | shai --trace | shai -p "now run it!"

The --trace flag in the middle is what makes that composition work, since the first call's output has to reach the second call in a form it can consume.

There is a third mode, interactive pipe, which is the bridge between the two:

echo "analyze this code" | shai -i

Content is piped in and the conversation continues in the TUI, so you can seed a session with a file or a command output and then take over.

And the HTTP server mode runs shai as a service:

shai serve --port 3000

The endpoints exposed are OpenAI shaped. There is POST /v1/chat/completions for the Chat Completions API in ephemeral mode, POST /v1/responses for the Responses API in stateful or stateless form, GET /v1/responses/{id} to fetch a response by ID, POST /v1/responses/{id}/cancel to cancel one, and a multimodal pair at /v1/multimodal and /v1/multimodal/{session_id}. The distinction between ephemeral and stateful is the same distinction the session commands make in the TUI, expressed as an API choice.

The shell assistant and the AGENTS.md context file

The shell assistant is the feature that ties shai to your terminal rather than to a separate window. It works by injecting command hooks while monitoring your terminal output, and when a command fails it proposes a fix.

The control is three commands:

shai on      # Start monitoring
shai off     # Stop monitoring
shai status   # Check if shai is active

The alignment in those comments is uneven in the source listing, which is a small sign that the table is maintained by hand rather than generated.

The context mechanism is AGENTS.md, described as a standard markdown file at the root of your project containing build steps, code style guidelines, testing instructions and other context for AI coding agents. shai loads context from two files in priority order: AGENTS.md, which is the canonical file and the recommended one, and SHAI.md, which is a legacy override or supplement and is deprecated.

For monorepos the rule is specific and useful: place an AGENTS.md in each subdirectory, and the closest one to the edited file takes precedence. That is a sensible resolution rule, since the file nearest the code being changed is the one most likely to describe that code.

Skills are the second extension mechanism, described as composable, on-demand procedural instructions. They live in a directory per skill with a markdown file inside:

.shai/skills/
└── my-skill/
    └── SKILL.md

They are discovered from three places: the project directory .shai/skills/, the global directory ~/.config/shai/skills/, and built-ins embedded in the binary, with memory given as the example of a built-in, the persistent-memory protocol. The shadowing rule is worth knowing because it is a quiet behaviour: a same-named skill in a higher tier shadows the lower one, so you can override a built-in with your own version of it.

The TUI slash commands cover the rest of the surface: /auth to configure the provider, /agent to switch agent while keeping the conversation context, /restore and /latest for sessions, /temp for sampling temperature, /tc for the tool call method with auto, fc, fc2 and so, /theme, /tokens for usage, /tools, /skills, /mcp for servers and connection status, /regenerate and /exit.

Custom agents, MCP and what the docs do not settle

Custom agents replace the single global configuration. Instead of one setup, you can create agent configurations with specific providers, tools and system prompts, and they live under ~/.config/shai/agents/. The commands are:

shai agent           # Open agent picker in TUI
shai agent myagent   # Launch TUI with a specific agent
shai list agent      # List available agents

The full schema is in the agent configuration documentation rather than the README, which is the pattern throughout this project: the README gives you the shape and the docs directory carries the detail, with separate pages for agents, the TUI configuration including keyboard shortcuts, skills, and benchmarks.

MCP support is described in one line, configure specialised agents with MCP and OAuth support, and the slash command /mcp lists servers and connection status. The README does not describe the configuration format for MCP servers, so that has to come from the linked documentation.

The same honesty applies to a few other things worth flagging before you commit to this tool.

There is a benchmark harness. The README mentions a measurement harness that runs the agent against scripted tasks, with details in a benchmarks document, but no results are quoted in the README itself. Anyone comparing coding agents should treat that harness as a starting point for their own measurement rather than as a published figure.

The tool call method matters more than it looks. The /tc command takes auto, fc, fc2 and so, and the model note earlier said function calling models work best while others need structured output forced with /set so. If your provider does not support function calling, you are selecting a different protocol path, and that is worth knowing before you conclude the agent is unreliable.

MCP with OAuth support means the agent can hold credentials for third-party services. That is the point of the feature and also the reason to scope which MCP servers you configure, since each one is another system that can act on your behalf.

Editorial conclusion

Adopt shai if you want one agent binary that covers interactive work, scripted automation and a self-hosted OpenAI compatible endpoint, and you are happy to point it at an OVHcloud AI Endpoints key or another supported provider. Do not adopt it expecting an anonymous default, because the anonymous OVHcloud mode is limited to 2 requests per minute per IP and model, and confirm the tool call method your chosen model supports before relying on it. Before the first real task, sign in with shai auth, place an AGENTS.md at the root of the project so the agent knows your build and test steps, and check which skills you have enabled, since a project skill silently shadows a built-in of the same name.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. ovh/shai on GitHub
4. README
5. Releases