convez.ai
AgenteDesenvolvimento WebAvançado
JuryiBay

Local AI Agent — Agente de IA para Desenvolvimento Local

JuryiBay/local-ai-agent

Claude Code robusto rodando 100% local via Ollama + Python

Ver no GitHub
InicialPluginScore · de 0 a 100

Agent 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-agent

1 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

Estrelas
0
Forks
0
Acompanhando
0
Saúde
57%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

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 (по умолчанию)ollamaOLLAMA_HOST
LM Studio / vLLM / llama.cpp / OpenAIopenai (или 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.

Ver o original no GitHub

Bom para

Relacionados