MForege — AI Agent CLI

A command-line AI agent with a transparent, IDE-style interface: live tool activity, colored diffs on every file change, mission plans, and session persistence. Supports OpenAI, Ollama (free & local), and any OpenAI-compatible API (Groq, Together, etc.).

Install

pip install mforege

Or with pipx (recommended for CLIs — isolated env, command on PATH everywhere):

pipx install mforege

Or straight from source:

pip install git+https://github.com/munjurdev/MForege.git

First run — guided setup

No config files needed. The first mforege launches a 30-second wizard:

Where should MForege get its brain?
  [1] Groq    free cloud API — fastest option (recommended)
  [2] Ollama  free, 100% local (needs https://ollama.com installed)
  [3] OpenAI  paid API
  [4] Custom  any OpenAI-compatible endpoint

Pick one, paste your key (hidden input), done — config is saved to ~/.mforege/.env and works from every folder, forever. A ./.env in the current folder can override it for one project. Change your mind later with mforege --setup.

For Groq: grab a free key at https://console.groq.com (no credit card).

Features

Agent core

• Full tool loop — when the model calls a tool, the result is sent back so the model can use it in its answer (streaming and non-streaming); up to 10 rounds per message, configurable via AgentConfig.max_tool_rounds
• Streaming output — responses appear token by token, with a live ⏳ thinking Ns (Esc=stop) timer in the status bar while the model works
• Markdown rendering — assistant replies render formatted, live: **bold** becomes bold, `code` gets its own color, fenced code blocks, headers, • bullets and ▌ quotes all appear styled while the model streams — raw markdown syntax is never shown (agent-panel style)
• Esc to stop — press Esc while the agent works and it stops cleanly: the in-flight request unwinds, any partial answer is kept, and the turn ends immediately (Esc with text in the input clears the line instead)
• Personality + response control — friendly, witty, emoji-moderate; short answers for casual chat, clarifying questions for ambiguous or underspecified requests (never dumps giant tutorials or acts on invented details)

Tools

Safety

• Destructive commands blocked outright (rm -rf, git push --force, format, ...)
• Mutating actions require approval — file writes/edits show a colored diff before you confirm; commands show the exact line to be run
• Fail-closed — without a confirmation handler, mutating operations refuse rather than run unconfirmed
• Workspace-confined — path tools only operate inside the folder you choose at launch; ../ and symlink escapes are rejected
• Timeouts & caps — 30s command timeout, tool output capped so the context window never balloons

Chat-style interface (prompt_toolkit)

• Slash-command menu — type / and a live two-column popup appears (command + description); keep typing to filter, ↑/↓ to select, Enter to accept, Esc to close — exactly like a modern IDE command palette
• Structured welcome — a clean rounded box shows the agent name, model, and workspace on startup
• Bottom input box — the input stays pinned at the bottom in a bordered frame like a chat app; the transcript scrolls above it
• Scrolling — PgUp/PgDn (10 lines), Ctrl+↑/↓ or Shift+↑/↓ (1 line), and the mouse wheel all scroll the transcript; End returns to the live tail. While scrolled up the status bar shows ↑ N lines · End=bottom
• Scrollbar — a thin scrollbar on the transcript's right edge shows the viewport position (auto-hidden when everything fits on screen)
• Live activity stream — every tool call prints as · tool(args) ✓ (0.3s)
• Thinking timer — thinking Ns... runs until the first token arrives
• Colored diffs — + green / - red, shown before approval and in the transcript after the edit lands
• Plan statusline — [Plan 2/5] next: write the test after each reply
• Status bar — model, workspace, and shortcut hints always visible
• Keys — Enter sends, Shift+Enter adds a newline (Windows Terminal, cmd, Unix terminals). In VS Code's terminal use Alt+Enter for a newline — VS Code never transmits Shift+Enter to any program. Esc stops the agent (or clears the input), Ctrl+T expands the AI's thinking, Ctrl+C quits
• Slash commands — /help, /plan, /tools, /new, /history, /sessions, /resume, /bash, /byok, /interview, /diagnostics, /review, /copy, /export, /theme:toggle, /reasoning, /vscode-hint, /clear, /exit

Memory

• Conversation memory — history per session, clear resets it
• Auto-condense — when history nears the context window, old turns fold into a compact summary injected before the recent ones, so long missions never lose their start
• Context meter — live ctx ~12.3K (2%) in the status bar
• Session resume — every conversation auto-saves to disk. Launches start FRESH (no auto-continue); /sessions lists past chats and /resume [id] restores one explicitly

Resilience

• Request timeouts + automatic retries with backoff for transient failures
• Friendly errors for missing keys or Ollama not running
• UTF-8 output on Windows (emoji-safe), clean async shutdown

Setup

python -m venv env
env/Scripts/activate          # Windows (bash: source env/Scripts/activate)
pip install -r requirements.txt
pip install -e .              # installs the `mforege` command

After pip install -e ., MForege works from any terminal — including VS Code's — with the venv activated:

mforege                                    # in any folder (uses MForege's own .env)
mforege --workspace "C:\path\to\project"   # work inside another project

Backends

OpenAI — put your key in .env:

OPENAI_API_KEY=sk-...
LLM_MODEL=gpt-4o-mini

Ollama (free, local) — install from https://ollama.com, then:

ollama pull llama3
mforege --backend ollama --model llama3

Custom (e.g., Groq):

API_KEY=gsk_...
BASE_URL=https://api.groq.com/openai/v1
LLM_MODEL=llama-3.1-8b-instant

OpenRouter (one free key → 20+ free models):

API_KEY=sk-or-...
BASE_URL=https://openrouter.ai/api/v1
LLM_MODEL=deepseek/deepseek-r1:free

Switching models live

MForege ships a curated free-model catalog (Groq, OpenRouter :free, Ollama, OpenAI) defined in one place — app/models.py. Add or remove a model by editing one Model(...) line there; every menu picks it up automatically.

Switch mid-conversation — history is kept, and the choice persists:

/model            # list models for your provider
/model 2          # pick by menu number
/model kimi       # pick by short name
/model openai/gpt-oss-120b         # or paste any model id

The switch applies to your next message. mforege --setup also offers the catalog (and OpenRouter) instead of a bare model prompt.

Web search (optional)

1. Get a free API key at https://dashboard.exa.ai
2. Add to .env: EXA_API_KEY=your_key
3. Restart the CLI

Workspace

MForege can only read/write inside one folder — the one you choose:

mforege --workspace "C:\path\to\your\project"

The header shows the active workspace. To work in a different folder, restart with a different --workspace (or set WORKSPACE in .env).

Run

python main.py                  # from the project folder
mforege                         # from ANY folder (after pip install -e .)
mforege --backend ollama --model llama3
mforege --workspace "C:\path\to\your\project"

.env resolution: if the current folder has a .env, it wins; otherwise MForege falls back to its own .env — so API keys are found no matter where you launch it. Workspace defaults to the current directory.

CLI commands

Example session

Nice to meet you! 👋 I'm MForege.

You: create utils.py with a greet function, then test it
Assistant: thinking 2s...
  · todo_plan(action=set) ✓ (0.0s)
  · create_file(path=utils.py) ✓ (0.0s)
[?] MForege wants to: CREATE file 'utils.py' (95 chars)
  @@ -0,0 +1,3 @@
  +def greet(name):
  +    return f"Hello, {name}!"
    Allow? [y/N]: y
  ✓ Edit applied:
  @@ -0,0 +1,3 @@
  +def greet(name):
  ...
[Plan 2/4] next: run the tests

Adding your own tool

from app.agent.tools import create_tool

async def get_weather(city: str):
    return f"Sunny in {city}, 25C"

agent.register_tools(create_tool("get_weather", "Get weather for a city", get_weather))

Tests

env/Scripts/python -m pytest

202 tests covering conversation memory (including auto-condensation), the tool registry, the safe calculator, the web search tool, session persistence (save, list, resume), the terminal UI (scrolling, thinking blocks, live plan blocks, Windows Shift+Enter compatibility), system tools (path confinement, command classification, confirmation flow — sync and async, diffs, notifications), discovery tools (search/glob/read windows), the todo plan, and the agent's tool-call loop — all with a mocked LLM, no network needed.