https://github.com/afittestide/asimi-cli
An opinionated, safe & fast coding agent
https://github.com/afittestide/asimi-cli
ai-agents devtool tui
Last synced: 22 days ago
JSON representation
An opinionated, safe & fast coding agent
- Host: GitHub
- URL: https://github.com/afittestide/asimi-cli
- Owner: afittestide
- License: mit
- Created: 2025-09-04T05:23:52.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2026-01-26T10:19:18.000Z (28 days ago)
- Last Synced: 2026-01-27T00:27:29.330Z (27 days ago)
- Topics: ai-agents, devtool, tui
- Language: Go
- Homepage: https://asimi.dev
- Size: 76.9 MB
- Stars: 14
- Watchers: 0
- Forks: 1
- Open Issues: 30
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
# Asimi CLI
[](https://github.com/afittestide/asimi-cli/actions/workflows/ci.yml?query=branch%3Amain)
> 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](https://podman.io/docs/installation) for the sandbox: like `docker` but safer
- [Just](https://github.com/casey/just) to collect all the scripts in a Justfile
Then, choose your installer flavor:
### One-liner (Recommended)
```bash
curl -fsSL https://asimi.dev/installer | bash
```
Or with wget:
```bash
wget -qO- https://asimi.dev/installer | bash
```
**Options:**
- `ASIMI_INSTALL_DIR=/path/to/dir` - Custom installation directory
- `ASIMI_VERSION=v0.1.0` - Install a specific version
### brew
```bash
brew tap afittestide/tap
brew install asimi
```
### Go
```bash
go install github.com/afittestide/asimi@latest
```
### Binaries
Download the binary from your platform from [latest releases](https://github.com/afittestide/asimi-cli/releases/latest) 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 `:!`.
### Configuration Options
The sandbox can be configured in `.agents/asimi.conf` (project-level) or `~/.config/asimi/asimi.conf` (user-level).
```toml
[run_shell_command]
# 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-: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](https://github.com/afittestide/asimi-cli/issues/56) | Model Context Protocol integration |
| [#110 - Streaming Improvements](https://github.com/afittestide/asimi-cli/issues/110) | Better streaming response handling |
| [#24 - Sub-agents & Roles](https://github.com/afittestide/asimi-cli/issues/24) | Task delegation with orchestrator role |
| [#8 - Git Integration](https://github.com/afittestide/asimi-cli/issues/8) | `:branch` command and tighter git workflows |
| A few directories | While flat is better than nested, there comes a time for dirs|
> 💡 Have a feature request? [Open an issue](https://github.com/afittestide/asimi-cli/issues/new)!
## 🛠️ 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.
```bash
# 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](https://github.com/afittestide/langchaingo)** - Using our own fork for model communications
- **[Bubble Tea](https://github.com/charmbracelet/bubbletea)** - Terminal UI framework
- **[Koanf](https://github.com/knadh/koanf)** - Configuration management
- **[Kong](https://github.com/alecthomas/kong)** - CLI argument parser
- **[Glamour](https://github.com/charmbracelet/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:
```bash
# 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.
## 🙏 Acknowledgments
- Built with ❤️ using Go
- Inspired by vi and his great grandchildren - the coding agents
- Special thanks to the Bubble Tea and LangChainGo communities