Local AI Agent — Agente de IA para Desenvolvimento Local
JuryiBay/local-ai-agent
Claude Code robusto rodando 100% local via Ollama + Python
Ver no GitHubAgent terminal baseado em Ollama que funciona localmente no seu computador, sem dependência de APIs na nuvem. Oferece 20 ferramentas para leitura/edição de arquivos, execução de comandos, gerenciamento de dependências, análise de erros e controle de git — com camada de segurança e memória de contexto.
Instalação
npx convez-ai JuryiBay/local-ai-agent1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Desenvolvimento assistido de código em ambiente isolado
- Automatização de tarefas repetitivas (refatoração, linting, commits)
- Análise e correção de erros sem enviar código para a nuvem
- Gestão de projetos multi-arquivo com contexto persistente
Veredito

MVP honesto e funcional que entrega o que promete: um agente de coding local robusto, com segurança e memória. Limitações técnicas da inferência local são claras e realistas — ideal para desenvolvedores que valorizam privacidade e controle total.
README
A tradução para o português deste README ainda está na fila.
local-ai-agent
Локальный терминальный AI coding-агент на базе Ollama. По духу — как Claude Code, но работает на твоём компьютере, через твою локальную модель, без облачных API по умолчанию.
Это честный MVP, который реально запускается, а не клон ChatGPT/Claude с нуля. Мы берём готовую open-weight модель и строим вокруг неё безопасного терминального агента.
Что он умеет (цель проекта)
- видеть проект, читать и редактировать файлы;
- запускать команды (через безопасный слой);
- ставить зависимости (pip/npm) с подтверждением;
- поднимать и останавливать dev-серверы;
- анализировать ошибки и предлагать исправления;
- показывать
git diff, готовить commit message; - работать пошагово и помнить проект.
Чего он НЕ умеет / чем слабее Claude Code
- локальная модель слабее в рассуждениях и медленнее;
- хуже держит длинный контекст;
- function-calling менее надёжен → используется свой устойчивый протокол
<tool_call>; - это не облачный сервис и не «полный ИИ» — это инструмент поверх локальной модели.
Требования
- OS: Windows 10/11 (приоритет), также macOS/Linux.
- Python: 3.11+ (код совместим и с 3.9 для разработки).
- Ollama + одна coding-модель.
- Желательно: Git, Node.js/npm.
Модель под железо
| Железо | Модель | Заметки |
|---|---|---|
| RTX 5080 / 16 ГБ VRAM (рекомендация) | qwen2.5-coder:14b | отлично влезает, быстро, умнее 7b |
| слабее / нужна скорость | qwen2.5-coder:7b | быстрый дефолт для MVP |
| мощное, готов к медленному | qwen2.5-coder:32b | в 16 ГБ целиком не влезет, уйдёт на CPU |
Установка (Windows PowerShell)
# 1. Ollama
winget install Ollama.Ollama
ollama pull qwen2.5-coder:14b # или :7b
ollama list # проверить
# 2. Python-зависимости
cd C:\Projects\local-ai-agent
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
# 3. Проверка окружения
python -m local_agent doctor
# 4. Запуск в папке твоего проекта
python -m local_agent --workspace C:\Projects\my-app
macOS/Linux: то же самое, активация venv через source .venv/bin/activate.
После pip install -e . появится короткая команда local-agent.
Запуск и режимы
python -m local_agent # интерактив в текущей папке
python -m local_agent --workspace . # указать папку
python -m local_agent --model qwen2.5-coder:14b
python -m local_agent --safe # больше подтверждений
python -m local_agent --auto # SAFE автоматом, рискованное — спрашивает
python -m local_agent --dangerously-auto-confirm # для опытных (разрушительное всё равно блокируется)
python -m local_agent doctor # проверка окружения
python -m local_agent models # список моделей Ollama
python -m local_agent init # создать .local-agent/ в проекте
python -m local_agent memory show # (память — на будущем этапе)
Без Ollama (офлайн-проверка агента)
$env:LOCAL_AGENT_PROVIDER="echo"
python -m local_agent --workspace .
Команды в REPL
/help · /exit · /model [имя] · /workspace · /clear · /status
/diff · /servers · /stop <id> · /memory (/memory clear) · /undo
Подкоманды CLI
python -m local_agent doctor # проверка окружения
python -m local_agent models # модели Ollama
python -m local_agent tools # список доступных инструментов
python -m local_agent init # создать .local-agent/
python -m local_agent memory show # память проекта
python -m local_agent config show # эффективные настройки
python -m local_agent config set model qwen2.5-coder:14b # сохранить настройку
python -m local_agent config set safety_mode safe --global # глобально
Провайдеры LLM
По умолчанию — Ollama (без облака). Архитектура позволяет переключаться:
| Провайдер | LOCAL_AGENT_PROVIDER | Доп. переменные |
|---|---|---|
| Ollama (по умолчанию) | ollama | OLLAMA_HOST |
| LM Studio / vLLM / llama.cpp / OpenAI | openai (или lmstudio/vllm) | OPENAI_BASE_URL, OPENAI_API_KEY |
| Офлайн-заглушка | echo | — |
Пример для LM Studio:
$env:LOCAL_AGENT_PROVIDER="openai"
$env:OPENAI_BASE_URL="http://localhost:1234/v1"
python -m local_agent --model your-model --workspace .
Инструменты (20)
project_scan · find_relevant · list_dir · read_file · search_text
write_file · edit_file · multi_edit · apply_patch · run_command
git_status · git_diff · git_add · git_commit · install_package
remember · recall · start_server · list_servers · stop_server
Полный список с описаниями: python -m local_agent tools.
Плагины (свои инструменты)
Положи .py с функцией get_tools() в <workspace>/.local-agent/plugins/
(или глобально в ~/.local-agent/plugins/) — инструменты подхватятся автоматически.
Готовый пример: examples/plugins/word_count.py.
Как написать свой — в CONTRIBUTING.md.
Настройки и персистентность
Приоритет: флаг CLI → переменная окружения → .local-agent/config.json проекта →
~/.local-agent/config.json глобально → значение по умолчанию.
Управление: config set <ключ> <значение> [--global]. Ключи: model, provider,
ollama_base_url, safety_mode, max_tool_calls, max_context_chars.
Безопасность (коротко)
- Агент действует только через tools, никогда не исполняет shell «из текста модели».
- Команды классифицируются: SAFE / CONFIRM / DANGEROUS / BLOCKED.
- Агент не повышает права, не обходит UAC, не отключает защиту Windows.
- Разрушительные команды (
Remove-Item -Recurse C:\Windows,format,shutdown…) блокируются даже в «опасном» режиме (или требуют двойного подтверждения). - Секреты (
.env,*.key,id_rsa…) не читаются без подтверждения и маскируются. - Агент работает в границах workspace; выход за пределы — с подтверждением.
Admin mode
Если команда требует прав администратора, агент скажет об этом, но сам права не повышает. Запусти PowerShell «от имени администратора» вручную, если это действительно нужно. При запуске под админом агент выводит предупреждение; safety policy остаётся активной.
Архитектура
CLI / REPL → Agent loop → LLM (Ollama)
│
├─ Tools (fs, shell, git, packages, servers)
├─ Safety policy (классификация + подтверждения)
├─ Workspace boundary (границы папки)
└─ Memory (SQLite) + Logs
Текущая структура пакета:
local_agent/
__main__.py # python -m local_agent
cli.py # argparse + REPL
config.py # AgentConfig
llm_client.py # Ollama + echo-заглушка
doctor.py # проверка окружения
platform_utils.py # ОС, admin, shell
prompts.py # системные промпты
ui/console.py # вывод (rich)
tools/ safety/ memory/ workspace/ schemas/ # этапы 3–11
Прогресс по этапам — в ROADMAP.md.
Типичные проблемы
| Симптом | Причина / решение |
|---|---|
Ollama не отвечает | не запущен → открой Ollama / ollama serve |
Модель не найдена | ollama pull qwen2.5-coder:7b |
python не найден | установи Python 3.11+, перелогинься |
Activate.ps1 нельзя запустить | Set-ExecutionPolicy -Scope CurrentUser RemoteSigned |
| мало VRAM | возьми модель меньше (:7b) |
| команда требует admin | запусти PowerShell от имени администратора вручную |
Статус
MVP-ядро завершено (Этапы 1–12). Реализовано:
- CLI, REPL,
doctor, Ollama-клиент, echo/scripted-режимы; - агентный цикл с парсером
<tool_call>и лимитом вызовов; - файловые инструменты (list/read/write/edit/search), границы workspace, защита секретов;
- safety-слой (SAFE/CONFIRM/DANGEROUS/BLOCKED) с подтверждениями и блокировкой опасного;
- shell-инструмент
run_command(таймаут, обрезка вывода); - git-инструменты (status/diff/add/commit);
- сканер проекта + контекст (тип проекта, ключевые файлы, команды запуска);
- установка пакетов (pip/npm/pnpm/yarn) с подтверждением;
- управление dev-серверами (start/list/stop, pid, логи);
- SQLite-память (
remember/recall, контекст проекта переживает перезапуск, лог tool-вызовов); - файловые логи сессий, маскирование секретов.
Плюс пост-MVP волна: OpenAI-совместимый провайдер, персистентность настроек
(config, глобальный fallback), обрезка контекста, бэкапы + /undo,
multi_edit/apply_patch, лексический ретривер find_relevant, плагины,
стриминг ответа, документация (ARCHITECTURE.md, CONTRIBUTING.md).
103 теста зелёных. 20 инструментов. Код прошёл независимое code- и security-ревью
(найденные баги и обходы safety исправлены). На Windows достаточно подключить живую
модель в Ollama (или LM Studio через openai-провайдер) — и сценарии из ТЗ работают.
См. ROADMAP.md и ARCHITECTURE.md.