asimi

README

Asimi CLI

A safe, opinionated coding agent

Asimi is an opinionated, safe & fast coding agent for the terminal

✨ Features

• 📦 Integrated Podman Sandboxes - Agent's shell runs in its own container
• 🎨 vi mimicry - Asimi is based on the fittest dev tool and its reincarnations vim and neovim
• 🤖 Multiple AI Providers - Support for Ollama, Claude Pro/Max and OpenAI API v1 compatible services
• 🧹 Less Clutter - Asimi's special files are under .agents directory and TOML is used for .conf
• 🔧 Fast Shell - Asimi's shell runs in a container and is >100 times faster than the others
• 📊 Context Awareness - Smart token counting and context visualization
• 🎯 Session Management - Save and resume your coding sessions

🚀 Quick Start

First, there are two great tools required on your system:

• Podman for the sandbox: like docker but safer
• Just to collect all the scripts in a Justfile

Then, choose your installer flavor:

brew

brew tap afittestide/tap
brew install asimi

Go

go install github.com/afittestide/asimi@latest

Binaries

Download the binary from your platform from latest releases and copy to your favorite bin directory e.g, /usr/local/bin.

First Steps

To start Asimi in interactive mode, type asimi.

1. Initialize your repo: :init - Creates AGENTS.md and Justfile if missing, and prepares the sandbox image

2. Check your container: :!uname -a - Runs shell commands in a persistent, containerized bash :!pwd - Should be the same path as on your host

🏝️ The Sandbox

Asimi uses podman to run the agent's shell in its own container. podman is compatible with docker so there's no need to learn new commands. Asimi uses it instead of docker because it's more secure - on linux it doesn't require a daemon.

The sandbox is based on .agents/sandbox/Dockerfile which is created by the init command. To build the image run just build-sandbox for an image named as in: asimi-sandbox-afittestide-asimi-cli. Asimi will launch a container based on this image the first time the model calls the shell tool. The container will stay up as long as the program is running. Once the program exits, the container is shutdown and removed.

Some commands, like gh, can't run in the sandbox. For these commands you can add a special exception in the config file.

To run commands in the container use :!<shell command>.

Configuration Options

The sandbox can be configured in .agents/asimi.conf (project-level) or ~/.config/asimi/asimi.conf (user-level).

[run_in_shell]
# Regex patterns for commands to run on the host (requires user approval)
run_on_host = ['^gh\s', '^podman\s']
# Regex patterns for commands to run on the host WITHOUT approval (safe, read-only)
safe_run_on_host = ['^gh\s+(issue|pr)\s+(view|list)', '^git\s+status']

[container]
# Custom container image name (default: asimi-sandbox-<project-name>:latest)
image_name = "localhost/my-custom-sandbox:latest"

# Additional mount points for the container
# Useful for mounting secrets, caches, or other project directories
[[container.additional_mounts]]
source = "/path/to/host/dir"
destination = "/path/in/container"

[[container.additional_mounts]]
source = "/another/host/path"
destination = "/another/container/path"

Environment Variables:

You can also configure the sandbox using environment variables:

• ASIMI_CONTAINER_IMAGE_NAME - Override the container image name
• ASIMI_CONTAINER_ADDITIONAL_MOUNTS - JSON string of additional mounts (e.g., [{"source":"/host","destination":"/container"}])

⌨️ vi FTW

Asimi mimics the vi/vim/neovim interface and extends the traditional modes:

Traditional Modes

• Insert Mode For typing your prompts
• Normal Mode Navigation and editing the prompt
• Command Mode Entering agents commands
  • :help - Show help
  • :context - View token usage and context
  • :new - Start a new conversation
  • :resume - resume an old session

New Modes

• Scroll Mode Use CTRL-B to enter the mode and scroll with your keys
• Select Mode For choosing a session to resume, a model to connect to, etc.

🗺️ Roadmap

Asimi is just starting out. It's been used to develop itself since version 0.1.0, well over a month now and it rarely breaks 🪬🪬🪬

Feature	Description
#56 - MCP Support	Model Context Protocol integration
#24 - Sub-agents & Roles	Task delegation with orchestrator role
#8 - Git Integration	:branch command and tighter git workflows
#68 - Shell Firewall	Required approval to run commands on host
A few directories	While flat is better than nested, there comes a time for dirs

💡 Have a feature request? Open an issue!

🛠️ Development

Principles

• Before the 🦙 comes the dev
• Mimicking is better than innovation
• ex/vi/vim/neovim are the best TUI ever made
• User's host is sacred and 🦙 access should be as restricted
• Integrations are great, let's have more of these

Prerequisites

• Go 1.25 or higher
• just bootstrap

Common Tasks

We're using a Justfile to collect all our scripts. If you need a new script please add a recipe in the Justfile.

# List recipes
just

# run Asimi
just run

# Run tests
just test

# measure shell's  performance
just measure

Project Structure

Flat. Please refrain from adding directories and files.

📦 Libraries

• LangChainGo - Using our own fork for model communications
• Bubble Tea - Terminal UI framework
• Koanf - Configuration management
• Kong - CLI argument parser
• Glamour - Markdown rendering

🔒 Security

Asimi takes security seriously:

• API keys are stored securely in your system keyring
• No data is sent to third parties except your chosen AI provider
• Shell commands are executed in a containerized sandbox

🤝 Contributing

We welcome contributions! Here are some ways you can help:

1. Report bugs - Open an issue with details
2. Suggest features - Share your ideas
3. Submit PRs - Fix bugs or add features

Commit Message Style

We use present progressive tense for commit messages:

# Good
git commit -m "feat: adding markdown support"
git commit -m "bug: fixing context overflow bug"

# Avoid
git commit -m "added markdown support"
git commit -m "fixed context overflow bug"

📝 Configuration

Asimi stores its configuration in ~/.config/asimi/asimi.conf (user-level) or .agents/asimi.conf (project-level). After first run the user's file is loaded with all the defaults.

Environment Variables

General Configuration

All configuration options can be set via environment variables using the ASIMI_ prefix. The variable name should match the config path with underscores instead of dots. For example:

• ASIMI_LLM_PROVIDER=anthropic sets llm.provider
• ASIMI_LLM_MODEL=claude-sonnet-4-20250514 sets llm.model
• ASIMI_UI_MARKDOWN_ENABLED=true sets ui.markdown_enabled

System Variables

• EDITOR - Preferred text editor for :export commands (default: system default)
• SHELL - Shell to use in container sessions (default: /bin/bash)

API Keys & Authentication

• ANTHROPIC_API_KEY - API key for Anthropic Claude models (alternative to OAuth)
• ANTHROPIC_OAUTH_TOKEN - OAuth token for Anthropic API (takes priority over keyring). Supports three formats:
  • Raw access token: sk-ant-...
  • JSON format: {"access_token":"...", "refresh_token":"...", "expiry":"...", "provider":"anthropic"}
  • Base64-encoded JSON (useful if copying from keychain)
• ANTHROPIC_BASE_URL - Custom base URL for Anthropic API (e.g., for proxy or custom endpoint)
• OPENAI_API_KEY - API key for OpenAI GPT models
• GEMINI_API_KEY - API key for Google Gemini models

OAuth Configuration (Advanced)

For custom OAuth setups, you can override the default OAuth endpoints:

Google/Gemini:

• GOOGLE_CLIENT_ID - OAuth client ID
• GOOGLE_CLIENT_SECRET - OAuth client secret
• GOOGLE_AUTH_URL - Authorization URL (optional, default: https://accounts.google.com/o/oauth2/v2/auth)
• GOOGLE_TOKEN_URL - Token URL (optional, default: https://oauth2.googleapis.com/token)
• GOOGLE_OAUTH_SCOPES - Comma-separated list of scopes (optional, default: generative-language scope)

OpenAI:

• OPENAI_CLIENT_ID - OAuth client ID
• OPENAI_CLIENT_SECRET - OAuth client secret
• OPENAI_AUTH_URL - Authorization URL
• OPENAI_TOKEN_URL - Token URL
• OPENAI_OAUTH_SCOPES - Comma-separated list of scopes (optional)

Anthropic:

• ANTHROPIC_CLIENT_ID - OAuth client ID
• ANTHROPIC_CLIENT_SECRET - OAuth client secret
• ANTHROPIC_AUTH_URL - Authorization URL
• ANTHROPIC_TOKEN_URL - Token URL
• ANTHROPIC_OAUTH_SCOPES - Comma-separated list of scopes (optional)

Development & Testing

• ASIMI_KEYRING_SERVICE - Override keyring service name (default: asimi-cli)
• ASIMI_SKIP_GIT_STATUS - Skip git status checks (set to any value to enable)
• ASIMI_VERSION - Override version string for testing

Logs are rotated and stored in ~/.local/share/asimi/. When running with --debug, logs are instead written to asimi.log in the project root for quick inspection.

🐛 Troubleshooting

Common Issues

Q: Asimi won't start

# Check if the binary is executable
chmod +x asimi

# Try running with verbose logging
./asimi --debug

Q: Context overflow errors

# Check your context usage
:context

# Start a new conversation
:new

📄 License

MIT License

Copyright (c) 2025 opencode

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

🙏 Acknowledgments

• Built with ❤️ using Go
• Inspired by vi and his great grandchildren - the coding agents
• Special thanks to the Bubble Tea and LangChainGo communities

---

Made with 🪾 by the Asimi team

Safe, fun, and high-quality code generation

---