mico-agent 0.1.3

Terminal-first coding agent CLI for local and OpenAI-compatible models

mico ⚓

Turkish below first. English follows in the second half.

Yerel veya OpenAI-uyumlu modellerle çalışan, terminal odaklı bir coding agent CLI.

Status: alpha (0.1.1). CLI and runtime behavior may still change.

Türkçe

mico nedir?

mico, terminal içinde çalışan, kod okuma, düzenleme, komut çalıştırma ve test döngüsünü tek akışta yürüten bir agent CLI'dır. Yerel model çalıştırmak isteyenler için tasarlanmıştır; MLX tabanlı modelleri ve OpenAI-uyumlu sunucuları destekler.

Ana hedefi şudur:

• modeli kendi makinenizde çalıştırmak
• kod görevlerini uçtan uca tamamlamak
• gereksiz servis bağımlılığı olmadan günlük geliştirme akışına oturmak

Öne çıkanlar

• Yerel model veya OpenAI-uyumlu sunucu ile çalışma
• Araç tabanlı agent akışı: dosya okuma/yazma, bash, test, git, HTTP
• Otomatik patch + test döngüsü
• REPL ve tek seferlik komut modu
• Donanıma göre profil ve model önerileri
• Oturum geçmişi, compact summary ve devam etme akışı
• Telemetry yok
• Apache-2.0 lisans

Kimler için?

mico, özellikle şu kullanım için uygun:

• Apple Silicon üzerinde MLX model çalıştıran geliştiriciler
• Linux üzerinde yerel ya da self-hosted model kullanan ekipler
• Kod agent'ını terminal iş akışına yakın kullanmak isteyenler

Hızlı başlangıç

pip install mico-agent
pip install 'mico-agent[mlx]'   # MLX backend kullanacaksan
mico

İlk çalıştırmada mico:

1. Python ortamını ve donanımı kontrol eder
2. yerel model klasörlerini tarar
3. uygun profil önerir
4. ayarları ~/.mico/ altına kaydeder
5. interaktif oturumu başlatır

Kurulum seçenekleri

PyPI

pip install mico-agent

MLX ile yerel model çalıştırmak istiyorsanız:

pip install 'mico-agent[mlx]'

Kaynaktan

git clone https://github.com/CaptainOnedin/mico.git ~/mico
~/mico/bin/mico

İsterseniz bin/mico için bir symlink ekleyebilirsiniz:

ln -s ~/mico/bin/mico /opt/homebrew/bin/mico   # macOS
ln -s ~/mico/bin/mico ~/.local/bin/mico        # Linux

Günlük kullanım

mico                    Interaktif REPL
mico ask "prompt"       Tek seferlik çalıştır
mico setup              Kurulumu yeniden çalıştır
mico models             Algılanan modelleri listele / indir
mico --doctor           Python, donanım ve profil tanısı
mico server-stop        Çalışan model sunucusunu durdur

REPL ve TUI davranışı

mico tam ekran bir uygulama olmaya çalışmaz. Çıktı doğrudan terminale akar; scrollback doğal kalır.

Öne çıkan davranışlar:

• slash komutları: /help, /mode, /thinking, /model, /history, /save, /clear
• @ ile dosya tamamlama
• canlı alt durum çubuğu: model, mod, context, network, tok/s
• JSON-aware streaming: ham action JSON kullanıcıya gösterilmez
• spinner ve stream çıktısı birlikte çalışır
• Ctrl+D ile temiz kapanış

Desteklenen çekirdek akış

Bu repo şu yüzeyi çekirdek ve desteklenen akış olarak görüyor:

Yüzey	Durum
mico interaktif REPL	Destekleniyor
mico ask	Destekleniyor
Model keşfi / seçim	Destekleniyor
mico --doctor	Destekleniyor
Agent tool loop	Destekleniyor
Slash komutları	Destekleniyor

Deneysel veya opsiyonel parçalar

Kod tabanında bulunan ama çekirdek akış kadar stabil kabul edilmeyen parçalar:

• yerel RAG akışı: mico-agent[rag]
• çok-rollü orchestration
• farklı backend ve model aileleri için ileri seviye tuning

Sistem gereksinimleri

• Python 3.11+
• macOS veya Linux
• yerel model kullanacaksan yeterli RAM / unified memory

Kabaca:

• 8B sınıfı modeller için ~8 GB
• 14B+ sınıfı modeller için 24 GB+ daha gerçekçi

Kapsam ve güvenlik

mico çekirdek olarak coding ve developer workflow'a odaklanır. Güvenlik/pentest araçları ayrı tutulur. Amaç, ana CLI'ın kapsamını net ve bakımı kolay tutmaktır.

Sorun giderme

Önce şunu çalıştırın:

mico --doctor

Bu çıktı şunları net gösterir:

• kullanılan Python
• aktif venv
• donanım özeti
• seçili profil
• model yolu

Issue açarken mico --doctor çıktısı faydalıdır.

Lisans

Apache-2.0. Ayrıntılar için LICENSE ve NOTICE.

Katkı

Katkı akışı için CONTRIBUTING.md.

---

English

What is mico?

mico is a terminal-first coding agent CLI that can read files, edit code, run commands, and iterate through patch-and-test loops. It is designed for local-model workflows and supports MLX-based setups as well as OpenAI-compatible servers.

Its core goal is straightforward:

• run the model on your own machine
• complete coding tasks end-to-end
• fit into a normal developer workflow without unnecessary service dependencies

Highlights

• Works with local models and OpenAI-compatible endpoints
• Tool-driven agent loop: file read/write, bash, tests, git, HTTP
• Automatic patch + test workflow
• Interactive REPL and one-shot mode
• Hardware-aware profile and model selection
• Session persistence and compact history summaries
• No telemetry
• Apache-2.0 licensed

Who is it for?

mico is a good fit for:

• developers running MLX models on Apple Silicon
• teams using local or self-hosted models on Linux
• people who want an agent CLI close to a normal terminal workflow

Quick start

pip install mico-agent
pip install 'mico-agent[mlx]'   # if you want the MLX backend
mico

On first launch, mico:

1. checks the Python environment and hardware
2. scans local model locations
3. recommends a suitable runtime profile
4. stores configuration under ~/.mico/
5. starts the interactive session

Installation

From PyPI

pip install mico-agent

For MLX-backed local inference:

pip install 'mico-agent[mlx]'

From source

git clone https://github.com/CaptainOnedin/mico.git ~/mico
~/mico/bin/mico

Optional symlink:

ln -s ~/mico/bin/mico /opt/homebrew/bin/mico   # macOS
ln -s ~/mico/bin/mico ~/.local/bin/mico        # Linux

Daily commands

mico                    Interactive REPL
mico ask "prompt"       One-shot execution
mico setup              Re-run setup
mico models             List or download detected models
mico --doctor           Python, hardware, and profile diagnostics
mico server-stop        Stop the running model server

REPL and TUI behavior

mico does not try to be a heavy fullscreen app. Output streams directly to the terminal and keeps normal scrollback intact.

Notable behaviors:

• slash commands: /help, /mode, /thinking, /model, /history, /save, /clear
• @ file completion
• live bottom status bar: model, mode, context, network, tok/s
• JSON-aware streaming: raw action JSON is hidden from the user
• spinner and streaming output are coordinated
• clean shutdown on Ctrl+D

Supported core workflow

This repo treats the following as the supported core surface:

Surface	Status
mico interactive REPL	Supported
mico ask	Supported
Model discovery / selection	Supported
mico --doctor	Supported
Agent tool loop	Supported
Slash commands	Supported

Experimental or optional pieces

The codebase also contains features that are not considered as stable as the core path:

• local RAG flow: mico-agent[rag]
• multi-role orchestration
• advanced tuning for different backends and model families

System requirements

• Python 3.11+
• macOS or Linux
• enough RAM / unified memory for the model you plan to run

Rough guidance:

• around 8 GB for 8B-class models
• 24 GB+ is a more realistic target for 14B+ models

Scope and security

mico is focused on coding and developer workflows. Security and pentest tooling are intentionally kept separate so the main CLI stays clear in scope and easier to maintain.

Troubleshooting

Start with:

mico --doctor

It reports:

• active Python
• active venv
• hardware summary
• selected profile
• model path

Including mico --doctor output in bug reports is useful.

License

Apache-2.0. See LICENSE and NOTICE.

Contributing

See CONTRIBUTING.md.