Skip to content

Repository files navigation

Fluxion AI, Silver Sponsor: one unified API for GPT, Claude and other leading AI models. Save up to 70% compared with official API pricing and get $3 in API credits.

AgentiLoopGo

🌐 English · Español · Français · Deutsch · 中文 (简体) · Русский · 한국어 · 日本語

🎉 We just shipped release v0.0.2 for Mac, Windows and Linux!


Take it for a spin! Read the README and see how long it takes you to get AgentiLoop up and running. If you hit any issues, let us know. We'd love your feedback.

Bonus: A Rust version is available too: AgentiLoopCLI → https://github.com/AgentiLoop/AgentiLoopCLI

Try both and tell us which one does it better: Go or Rust? 🐹 vs 🦀


💖 Sponsor AgentiLoop

Like what you see? Help keep AgentiLoop fast and cross-platform. Sponsor us on GitHub Sponsors → AgentiLoop. Tiers and perks are in the Sponsorship guide.

Sponsor AgentiLoop


AgentiLoop is an AI coding agent that runs in your terminal, in the spirit of Claude Code. You describe what you want in plain language. The agent reads your files, edits code and runs commands to get it done, and it asks your permission before it changes anything.

It's written in Go and runs on macOS, Linux and Windows. It is the Go twin of AgentiLoopCLI (Rust): same features, same options, same settings, session and MCP files, so you can switch between them freely. It works with Claude (Anthropic), OpenAI, local models through Ollama or LM Studio, and oMLX on Apple Silicon.

Created with AgentiLoop Agent! This is our baby. Prebuilt binaries for macOS, Linux and Windows are on the Releases page, or compile it from source with Go.

AgentiLoop Coding in action

🚀 New here? Up and running in 5 minutes

No Rust, no Go, no compiling. You download one file, give it an API key and start chatting. Follow the steps in order.

1. Download AgentiLoop

First find out which file you need:

Your computer File to download
Mac with Apple Silicon (M1, M2, M3, M4…) agentiloop-macos-arm64.tar.gz
Mac with an Intel chip agentiloop-macos-x86_64.tar.gz
Linux, 64-bit PC agentiloop-linux-x86_64.tar.gz
Linux on ARM (Raspberry Pi 4/5, ARM servers) agentiloop-linux-arm64.tar.gz
Windows 10/11 agentiloop-windows-x86_64.zip

Not sure? On Mac or Linux, run uname -m. arm64 or aarch64 means arm64, and x86_64 means x86_64.

macOS and Linux. Open Terminal and paste these lines. This example uses the Apple Silicon file, so change macos-arm64 in the first three lines if yours is different:

curl -LO https://github.com/AgentiLoop/AgentiLoopGo/releases/download/v0.0.2/agentiloop-macos-arm64.tar.gz
tar xzf agentiloop-macos-arm64.tar.gz
mkdir -p ~/.local/bin && mv agentiloop-macos-arm64/agentiloop ~/.local/bin/

That puts the program in ~/.local/bin, a folder in your home directory. Step 3 tells your terminal to look there.

Windows. Open PowerShell (Start menu → type "PowerShell") and paste:

Invoke-WebRequest https://github.com/AgentiLoop/AgentiLoopGo/releases/download/v0.0.2/agentiloop-windows-x86_64.zip -OutFile agentiloop.zip
Expand-Archive agentiloop.zip -DestinationPath $HOME\agentiloop -Force
$p = [Environment]::GetEnvironmentVariable("Path", "User")
[Environment]::SetEnvironmentVariable("Path", "$p;$HOME\agentiloop\agentiloop-windows-x86_64", "User")

The last two lines add AgentiLoop to your PATH. Close PowerShell and open a new window so it picks up the change.

2. Get an API key

AgentiLoop is the agent. The "brain" is an AI model that you connect it to. Pick one:

Option Where to get it Cost
Claude (recommended) console.anthropic.com → Create Key. It starts with sk-ant- Pay per use
OpenAI platform.openai.com/api-keys. It starts with sk- Pay per use
Ollama (runs on your own computer) Install from ollama.com, then run ollama pull qwen2.5-coder Free, no key

Copy the key somewhere safe. You'll paste it in the next step.

3. Save your settings in your shell profile

Your shell profile is a small text file that your terminal reads every time it opens a new window. Put your settings there and you only have to do this once. If you skip it, you'd have to type your key again in every new terminal. That's the #1 reason people get stuck.

Which file is it?

System Shell (default) Profile file
macOS (Catalina 10.15 and newer) zsh ~/.zshrc
Most Linux distros bash ~/.bashrc
Linux or Mac with zsh zsh ~/.zshrc
fish shell fish ~/.config/fish/config.fish
Windows PowerShell none needed, see below

Not sure which shell you use? Run echo $SHELL. ~ means your home folder, so ~/.zshrc is e.g. /Users/you/.zshrc. Files that start with a dot are hidden in Finder and file browsers, which is normal.

Open the file. Use one of these (they create the file if it doesn't exist yet):

nano ~/.zshrc                        # works everywhere, right in the terminal
touch ~/.zshrc && open -e ~/.zshrc   # macOS: opens it in TextEdit

(Linux with bash: use ~/.bashrc instead of ~/.zshrc.)

Add these lines at the bottom. Keep only the key line you need, and paste your real key between the quotes:

# AgentiLoop
export PATH="$HOME/.local/bin:$PATH"

export ANTHROPIC_API_KEY="sk-ant-paste-your-key-here"          # Claude
# export OPENAI_API_KEY="sk-paste-your-key-here"               # OpenAI
# export OPENAI_BASE_URL="http://localhost:11434/v1"           # Ollama (no key needed)

Save and close. In nano: Ctrl-O, Enter, then Ctrl-X. In TextEdit: ⌘S, then close the window.

Load it. Either open a new terminal window, or run:

source ~/.zshrc

fish uses a different syntax. Put this in ~/.config/fish/config.fish:

fish_add_path $HOME/.local/bin
set -gx ANTHROPIC_API_KEY "sk-ant-paste-your-key-here"

Windows (PowerShell). Windows has no profile file to edit for this. Save the key as a user environment variable instead:

setx ANTHROPIC_API_KEY "sk-ant-paste-your-key-here"
# or: setx OPENAI_API_KEY "sk-..."   /   setx OPENAI_BASE_URL "http://localhost:11434/v1"

Then close PowerShell and open a new window. setx doesn't affect the window it runs in. You can also do this with the mouse: Start → Edit environment variables for your account → New….

🔒 Keep your key private. Don't commit your profile file to git or paste the key into chats. On a Mac you can keep it in the Keychain instead; see Step 2 of the Quick start.

4. Check that it works

agentiloop --version

You should see agentiloop 0.0.2. Now check that the key is loaded:

echo $ANTHROPIC_API_KEY | cut -c1-10    # macOS / Linux: should print sk-ant-...
$env:ANTHROPIC_API_KEY.Substring(0,10)  # Windows PowerShell

If it prints nothing, go back to step 3. The key isn't loaded yet.

5. Your first session

Go to a project folder and start the full-screen interface:

Start with a new, empty test folder so you can try it safely. For a real project, cd into that project's folder instead (for example cd ~/code/my-app).

mkdir -p ~/agentiloop-test
cd ~/agentiloop-test
agentiloop --tui

Using Ollama? Tell it the provider and a model you've pulled: agentiloop -p openai -m qwen2.5-coder --tui.

Now just type what you want in plain English and press Enter. Some good first prompts:

explain what this project does
list the files in src and tell me which one is the entry point
find the TODO comments and summarize them
add a --verbose flag to the command-line parser
run the tests and fix anything that fails
create a README.md for this project

Before the agent changes a file or runs a command, it asks you. Press y for yes, n for no, a to always allow that tool for the session, or Esc to skip the step. Press Ctrl-C to quit. Next time, a plain agentiloop starts the same way and picks up your last conversation.

Just want one answer without the chat? Pass the question as an argument:

agentiloop "explain what this project does"

What can it do? (tools)

The agent works with five built-in tools. You don't call them yourself. You describe the goal, and the agent picks the tool:

Tool What it does Asks first?
read_file Reads a file (with line numbers) No
list_dir Lists the files in a folder No
write_file Creates a new file or overwrites one Yes
edit_file Changes an exact piece of text in a file Yes
bash Runs a shell command, like tests, builds or git (sh -c on Mac/Linux, cmd /C on Windows) Yes

Want more tools, like web search, databases or GitHub? Add MCP servers; see Adding tools with MCP.

The help command

agentiloop --help lists every option:

$ agentiloop --help
AgentiLoop — a cross-platform agentic coding loop for your terminal.

Usage: agentiloop [OPTIONS] [PROMPT]...

Arguments:
  [PROMPT]...  One-shot prompt. If omitted, starts an interactive REPL

Options:
  -p, --provider PROVIDER   Model backend (PROVIDER): anthropic, openai (OpenAI-compatible: OpenAI, Ollama,
                            LM Studio, Groq, OpenRouter, … via OPENAI_BASE_URL), or omlx (local
                            oMLX server, http://localhost:8000/v1). Defaults to the last one used,
                            then auto-detected from which credentials are set. [env: AGENTILOOP_PROVIDER]
  -m, --model MODEL         MODEL id to use. Defaults to the last model used with this provider
                            (~/.agentiloop/settings.json), then the provider's default. [env: AGENTILOOP_MODEL]
      --yes                 Skip all permission prompts (dangerous; intended for CI). Never remembered. [env: AGENTILOOP_YES]
      --max-turns N         Max provider round-trips (N) per prompt [default: last used, then 50]
      --compact-at TOKENS   Summarize the conversation once a request reaches this many input TOKENS (0 = never)
                            [default: last used, then 150000] [env: AGENTILOOP_COMPACT_AT]
  -C, --cwd DIR             Working directory (DIR) the agent operates in (defaults to cwd)
  -r, --resume ID           Resume a saved session by ID (see /sessions)
  -c, --continue            Resume the most recent session for this working directory
                            (the default for interactive launches; kept for scripts)
      --new                 Start a new session instead of continuing the last one in this directory
      --tui                 Full-screen terminal UI instead of the line REPL. Remembered. [env: AGENTILOOP_TUI]
      --no-tui              Use the line REPL even if the TUI was used last time
      --no-mcp              Don't start MCP servers from ~/.agentiloop/mcp.json / ./.mcp.json. [env: AGENTILOOP_NO_MCP]
  -h, --help                Print help
  -V, --version             Print version

Inside a session, type /help to see the chat commands (/model, /sessions, /resume, /clear, /compact, /mcp, /exit). The full reference is in All options and Commands inside the chat.

Stuck? Quick fixes

You see Fix
command not found: agentiloop ~/.local/bin isn't on your PATH. Add the export PATH=... line from step 3, then open a new terminal. On Windows, open a new PowerShell window
Error: no provider credentials found No key is loaded. Redo step 3, then check it with step 4
macOS: "agentiloop" cannot be opened / unidentified developer This happens if you downloaded with a browser instead of curl. Run xattr -d com.apple.quarantine ~/.local/bin/agentiloop
Windows: Windows protected your PC Click More info → Run anyway
401 / invalid x-api-key / authentication error The key is wrong or has spaces or quotes in it. Copy it again and check the line in your profile
Ollama: model not found Run ollama list and pass the exact name with -m
It keeps using an old model or provider It remembers your last choices. Pass -p / -m to change them, or delete ~/.agentiloop/settings.json to reset

Still stuck? Open an issue and paste the command and the error. We'll help.


Quick start

Three steps: install it, give it a model, run it.

Step 1: Install

Download: grab the archive for your platform from Releases, unpack it and put agentiloop (agentiloop.exe on Windows) on your PATH.

Or build it: if you don't have Go yet (1.25 or newer), install it from go.dev/dl. Then:

go install github.com/AgentiLoop/AgentiLoopGo/cmd/agentiloop@latest

or from a clone:

git clone https://github.com/AgentiLoop/AgentiLoopGo.git
cd AgentiLoopGo
go install ./cmd/agentiloop

This builds the program and puts an agentiloop command on your PATH, in ~/go/bin (%USERPROFILE%\go\bin on Windows). No C compiler is needed.

Not installing? Everything in this README also works from inside the repo folder. Wherever you see agentiloop <options>, type go run ./cmd/agentiloop <options> instead.

Step 2: Connect a model

AgentiLoop needs a model to talk to. Pick one of these:

I want to use… Do this
Claude (Anthropic) export ANTHROPIC_API_KEY=sk-ant-...
OpenAI export OPENAI_API_KEY=sk-...
Ollama, LM Studio, or any OpenAI-compatible server export OPENAI_BASE_URL=http://localhost:11434/v1 (use your server's address; no key needed for local servers)
oMLX (local models on Apple Silicon) Usually nothing. Start oMLX, then run AgentiLoop with -p omlx (see below)

For Claude you can use a normal API key (sk-ant-api…) or a Claude Code token (sk-ant-oat01-…, which you get from claude setup-token). AgentiLoop detects which kind it is.

oMLX details. When oMLX runs on the same Mac, AgentiLoop reads the server port and API key from oMLX's own settings file (~/.omlx/settings.json), so you don't need to export anything. If oMLX runs on another machine, or you want to override those settings, export them yourself:

export OMLX_BASE_URL=http://192.168.1.50:7777/v1   # the oMLX server's address (or OMLX_PORT=7777 for localhost)
export OMLX_API_KEY=...                            # the API key from oMLX's settings

If oMLX has API key verification turned off, no key is needed.

An export only lasts for the terminal tab you typed it in. To make it permanent, add the line to your shell profile (~/.zshrc on macOS). On a Mac you can keep the key in the Keychain rather than in the file:

# one time: store the key in your Keychain
security add-generic-password -a "$USER" -s ANTHROPIC_API_KEY -w "sk-ant-..."

# in ~/.zshrc: load it for every new terminal
export ANTHROPIC_API_KEY="$(security find-generic-password -a "$USER" -s ANTHROPIC_API_KEY -w 2>/dev/null)"

Step 3: Run it

Go to the project you want to work on and start AgentiLoop:

cd ~/my-project
agentiloop --tui

--tui opens the full-screen interface, which we recommend. Type what you want, e.g. "find where the config file is loaded and add a --verbose flag", and press Enter.

You'll see the agent's replies, each tool it uses (🔧) and each result (✓ or ✖). The box at the bottom shows what it's doing right now, for example ✻ Thinking... 12s. Before it writes a file or runs a command, it asks you:

  • y: yes, this time
  • n: no
  • a: always allow this tool for the rest of the session
  • Esc: skip this step, but keep going

Three ways to use it

Mode Command Good for
TUI (full screen) agentiloop --tui Everyday use: scrolling history, live status, clickable links
Chat (line by line) agentiloop Simple terminals, or if you prefer plain text
One-shot agentiloop "explain this project" One question: it answers, then exits. Handy in scripts

Keys in the TUI: Enter sends · ↑ / ↓ go through earlier prompts · PgUp / PgDn or the mouse wheel scrolls · Ctrl-U clears the line · Ctrl-C quits.


It remembers your setup

You only type your options once. AgentiLoop saves how you launched it, so next time a plain agentiloop starts the same way:

agentiloop -p anthropic --tui    # first time: choose provider and TUI
agentiloop                       # from now on: same provider, same model, TUI, and your last conversation

What it remembers:

  • Provider (-p) and TUI on/off (--tui / --no-tui)
  • Model: the last one you used, separately for each provider. Switching back to a provider brings back its model.
  • Limits: --max-turns and --compact-at
  • Your conversation: it picks up the last conversation in the current folder, if that conversation used the same provider. The earlier messages are shown again on screen, so you can scroll back and see where you left off

To change something, pass the new option. It applies right away and is remembered from then on:

agentiloop -p omlx        # switch to oMLX (its last-used model comes back too)
agentiloop -m <model>     # switch model
agentiloop --no-tui       # back to the line-by-line chat
agentiloop --new          # start a fresh conversation (the old one stays saved)

Some things are never remembered on purpose:

  • --yes: skipping permission prompts has to be a deliberate choice every time
  • --no-mcp, -C and one-shot prompts
  • API keys: those stay in your shell profile

To forget everything, delete ~/.agentiloop/settings.json.


All options

Every option can also be set with an environment variable, shown in the second column. An option you type always beats a remembered value.

Option Env variable What it does
-p, --provider <name> AGENTILOOP_PROVIDER anthropic, openai or omlx. If you don't set one, AgentiLoop uses the last one, or detects it from your keys (Anthropic first, then OpenAI, then oMLX)
-m, --model <id> AGENTILOOP_MODEL Which model to use
--tui / --no-tui AGENTILOOP_TUI Full-screen interface on / off
--new Start a new conversation instead of continuing
-c, --continue Continue the last conversation here (already the default)
-r, --resume <id> Reopen a specific conversation (find ids with /sessions)
-C, --cwd <folder> Work in a different folder than the one you're in
--yes AGENTILOOP_YES Don't ask before running tools. ⚠️ Only for trusted, automated use
--no-mcp AGENTILOOP_NO_MCP Don't start MCP servers (see below)
--max-turns <n> Max steps the agent may take per request (default 50)
--compact-at <tokens> AGENTILOOP_COMPACT_AT When to summarize a long conversation (default 150000, 0 = never)
-h / -V Help / version

Some examples:

agentiloop -p openai -m gpt-4o-mini "summarize this repo"    # one question with a specific model
agentiloop -C ../other-repo --tui                            # work on another project
agentiloop --yes "run the tests and fix any failures"        # unattended, no prompts

Which model is used? The first one that applies wins:

  1. -m on the command line
  2. the model of the conversation you're continuing
  3. the last model you used with this provider
  4. the provider's default: claude-sonnet-5 for Anthropic, gpt-4o-mini for OpenAI, or the first model oMLX offers

Commands inside the chat

Type these at the prompt, in the TUI or the chat:

Command What it does
/model Show available models. /model 3 or /model <id> switches (and is remembered)
/sessions List your saved conversations, newest first
/resume <n or id> Reopen one of them
/clear Clear the conversation and start a new one
/compact Summarize the conversation now to free up space
/mcp Show connected MCP servers and their tools
/help List these commands
/exit Quit

Long conversations

Models can only read so much at once. When a conversation gets big (by default, when a request reaches 150,000 tokens), AgentiLoop asks the model to summarize it so far and carries on from the summary. You'll see a 📦 note when that happens. /compact does it on demand, and --compact-at 0 turns it off.


Adding tools with MCP (optional)

MCP servers give the agent extra tools, like database access, web search or your own scripts. List them in a JSON file:

  • ~/.agentiloop/mcp.json: available in every project
  • .mcp.json in a project folder: only in that project. If a name appears in both files, this one wins.

The format is the same one Claude Code, Claude Desktop and Agent! use, so you can copy existing configs:

{ "mcpServers": {
    "Local":  { "command": "my-mcp-server", "args": ["--flag"], "env": { "API_KEY": "${MY_KEY}" } },
    "Remote": { "url": "https://example.com/mcp", "headers": { "Authorization": "Bearer ${TOKEN}" } }
} }

How it works:

  • Two kinds of server. A server with a command is a local program that AgentiLoop starts for you. A server with a url is reached over HTTP. Newer "Streamable HTTP" and older "SSE" servers both work; a URL ending in /sse (or "transport": "sse") selects the older style.
  • Tool names. Each server tool shows up for the agent as mcp_<server>_<tool>, e.g. mcp_Local_search.
  • Secrets. ${VAR} (or ${VAR:-default}) is filled in from your environment, so keys don't need to be in the file.
  • Permissions. MCP tools ask permission like any other tool, unless the server marks a tool as read-only.
  • Turning servers off. Add "disabled": true to skip one server, or run with --no-mcp to skip them all.
  • Safety. Plain http:// is only allowed for localhost; remote servers need https://.

Type /mcp to see which servers connected, their tools, and any errors.


Where things are saved

Everything lives in ~/.agentiloop/. Set AGENTILOOP_HOME to use a different folder, e.g. a separate test profile.

File What's in it
settings.json Remembered provider, models and options. Delete it to reset
sessions/ Your conversations, one file each
mcp.json Your MCP servers
history.txt Prompts you've typed (for ↑ / ↓)

Other environment variables

You'll rarely need these:

Variable Use
ANTHROPIC_BASE_URL Send Anthropic requests to a proxy or compatible server
ANTHROPIC_OAUTH_TOKEN Alternative to ANTHROPIC_API_KEY for a Claude Code token
OMLX_BASE_URL, OMLX_PORT, OMLX_API_KEY oMLX server address and key. They override ~/.omlx/settings.json, which is read by default (port 8000 if neither is set)
AGENTILOOP_LOG=debug (or RUST_LOG=debug) Show debug logs, including token usage per request

For developers

Build and test

go build -o agentiloop ./cmd/agentiloop   # → ./agentiloop
go test ./...                             # runs offline, no API keys needed

Cross-compiling needs nothing extra, for example GOOS=windows GOARCH=amd64 go build ./cmd/agentiloop.

The tests don't touch the network. The agent loop runs against a scripted fake model, and the streaming parsers against a local test server. The TUI is drawn on tcell's simulated screen. The MCP client is tested against a bundled example server over all three connection types (stdio, HTTP, SSE). You can run that server yourself to try MCP by hand:

go run ./examples/mcp-example-server --http 8791   # or --sse 8792, or --stdio

How the code is organized

The project is split into five packages, and each one builds on the ones before it:

Package What's in it
core The heart: the agent loop, messages, the tool and provider interfaces, permissions, sessions, summarizing
provider Talks to the models: Anthropic, OpenAI-compatible servers, oMLX
tools Built-in tools: read_file, write_file, edit_file, list_dir, bash
mcp The MCP client, ported from Agent!'s Swift AgentMCP
cmd/agentiloop The agentiloop program: options, chat, TUI, settings

core, provider, tools and mcp use only the Go standard library, so they can be embedded in other programs.

Dependencies

Everything that isn't the TUI or the command line is standard library. The agentiloop program adds:

Module Used for
github.com/spf13/pflag Command-line options
github.com/peterh/liner The line-by-line chat
github.com/gdamore/tcell/v2, github.com/mattn/go-runewidth The TUI
github.com/yuin/goldmark, github.com/alecthomas/chroma/v2 Markdown and code highlighting

Roadmap

  • Streaming responses
  • OpenAI-compatible providers
  • Summarizing long conversations
  • Saved conversations
  • Full-screen TUI
  • MCP client
  • What's NeXT?

License

PolyForm Noncommercial 1.0.0. You may use, change and share this software for personal and noncommercial purposes. Commercial use, including building or selling commercial versions, is reserved to AgentiLoop. Contact AgentiLoop for a commercial license.


Fluxion AI, Silver Sponsor: one unified API for GPT, Claude and other leading AI models. Save up to 70% compared with official API pricing and get $3 in API credits.

About

Cross-platform agentic coding loop CLI written in Go (macOS / Linux / Windows) Created with AgentiLoop Agent!

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Sponsor this project

Packages

Contributors

Languages