PoopSeek

🚀 AI-агент в CLI с поддержкой 8 LLM-провайдеров, MCP, ACP, навыков и Figma-плагином

PoopSeek — это интерактивный TUI-агент на TypeScript + Bun. Умеет управлять файлами, запускать shell, ходить в MCP-серверы, делегировать задачи внешним ACP-агентам (Claude Code, Gemini CLI), генерировать UI прямо в Figma и автономно планировать действия в многошаговом agent loop.

✨ Особенности

🤖 Agent Loop — автономное планирование и выполнение действий (до 256 шагов на turn, streaming с AbortSignal и rate-limit retry)
🛠️ 31+ встроенных инструментов: file., bash/powershell, git/git.edit, agent.ask/parallel, memory., user.ask/choice/confirm, skill.read, todo.read/write и др.
🎨 Мульти-провайдер: DeepSeek web, OpenAI, OpenRouter, HuggingFace, Claude, Gemini, Ollama, LM Studio
🔌 MCP-клиент: stdio + Streamable HTTP, авто-discovery из Claude Desktop, VS Code, Cursor, Trae, статус-кэш с TTL
🔗 ACP-протокол: обе роли — server (poopseek --acp для Zed/JetBrains/Neovim) и client (/acp для управления внешними агентами)
📚 Skills: совместимость с Agent Skills spec, поиск в 49+ директориях
🎯 Figma plugin: HTTP/SSE сервер + плагин для генерации UI из текстового брифа (designer → builder → handyman pipeline)
🔍 RAG: гибридный семантический поиск по кодбазе (embeddings + BM25, RRF fusion) — codebase.index / codebase.search tools + /rag команда. Локальная SQLite-БД, модель ~120 МБ. См. docs/articles/rag.md
🧠 Auto-memory: персистентная память по проектам в ~/.poopseek/memories/
🎭 Roles: переключаемые «роли» агента с собственными промптами
📂 File mentions: @path/to/file автоматически читает файл и подкладывает в контекст
⚡ Bun runtime + Strict TypeScript 5+

🚀 Установка

Готовый бинарник (рекомендуется)

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/Aver005/poopseek/main/install.sh | bash

Windows (PowerShell):

irm https://raw.githubusercontent.com/Aver005/poopseek/main/install.ps1 | iex

Скрипт сам определит ОС/архитектуру, скачает последний релиз с GitHub, положит бинарник + assets рядом, добавит запуск в PATH. После — просто poopseek из любой папки.

Обновление: внутри poopseek команда /update или повторно запустить тот же скрипт.

Пиннинг версии: POOPSEEK_VERSION=v1.2.3 curl … | bash.

Из исходников (для разработки)

Требования: Bun v1.0+

git clone https://github.com/Aver005/poopseek.git
cd poopseek
bun install
bun start

При первом запуске откроется onboarding — выбери провайдер(ы), введи ключи. Конфиг сохранится в %APPDATA%/poopseek/config.json (Windows) или ~/.config/poopseek/config.json (POSIX).

Сборка локально

bun run build:windows         # Windows .exe → build/windows/poopseek.exe
bun run build:macos:arm64     # macOS Apple Silicon → build/darwin-arm64/poopseek
bun run build:macos:x64       # macOS Intel → build/darwin-x64/poopseek
bun run build:linux:x64       # Linux x64 → build/linux-x64/poopseek
bun run build:linux:arm64     # Linux ARM → build/linux-arm64/poopseek
bun run build:plugin          # Figma plugin → build/plugins/figma/

Все скрипты cross-compile через bun build --compile, так что любой target можно собрать с любого хоста.

При сборке exe можно передать --version 1.2.3. Если опущено — используется POOPSEEK_VERSION / APP_VERSION env, иначе "dev".

Релиз через GitHub Actions

Workflow .github/workflows/release.yml срабатывает на git-tag вида v* (или workflow_dispatch). Собирает все 5 платформ, кладёт архивы в GitHub Release. install.sh / install.ps1 тянут оттуда latest.

git tag v0.1.0
git push origin v0.1.0   # → CI соберёт релиз

🎮 Использование

Интерактивный режим

После запуска появится приглашение >. Пиши запросы на естественном языке — агент сам выберет тулы.

> создай файл test.txt с текстом "Hello World"
🔨 file.write
✓ Файл test.txt создан

> сколько строк в src/index.ts и каких импортов больше всего?
🔨 file.read
🔨 file.find
Файл содержит 84 строки, чаще всего импортируется из @/cli (...)

Slash-команды

Команда	Описание
`/help`	Список всех команд
`/clear`	Очистить историю (новый диалог)
`/compact`	Сжать историю через LLM-резюме
`/session`	ID текущей сессии
`/sessions`	Загрузить ранее сохранённую сессию
`/history`	Импорт истории чата DeepSeek web
`/stats`	Размер контекста
`/provider [id]`	Сменить провайдер
`/switch`	Быстрое переключение провайдера
`/model`	Сменить модель внутри провайдера
`/auth`	Управление токенами
`/logout`	Разлогиниться
`/mcp`	Управление MCP-серверами (list/tools/resources/prompts/connect/disconnect/info/reload/read/prompt)
`/acp`	Управление ACP-агентами (list/add/remove/connect/send/use/sessions/policy)
`/rag`	Семантический поиск по коду (status/init/on/off) — см. docs/articles/rag.md
`/skills`	Управление навыками
`/skills-folder`	Добавить пользовательскую папку с навыками
`/role`	Сменить активную роль
`/theme [dark\|light]`	Сменить цветовую тему
`/think`	Toggle thinking режима
`/web`	Toggle web search
`/refactor`	Запуск refactor pipeline
`/review`	Запуск review pipeline
`/btw <вопрос>`	Фоновый sidechat без прерывания основного диалога
`/exit`, `/quit`	Выйти

Полный список — /help.

MCP-серверы

Создай mcp.config.json в корне проекта:

{
  "servers": {
    "filesystem": {
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
    },
    "remote-api": {
      "transport": "http",
      "url": "https://example.com/mcp",
      "headers": { "Authorization": "Bearer ..." }
    }
  },
  "autoDiscover": true,
  "disabled": []
}

Если autoDiscover: true (по умолчанию) — поверх workspace-конфига подмешиваются серверы из Claude Desktop, VS Code, Cursor, Trae. Управление через /mcp.

ACP

Запуск как ACP-сервера (для Zed/JetBrains/Neovim):

poopseek --acp

В Zed settings.json:

{
  "agent_servers": { "poopseek": { "command": "poopseek", "args": ["--acp"] } }
}

Подключение внешних ACP-агентов: /acp add claude claude acp → /acp connect claude → /acp use claude (proxy-tool agent__claude появляется в распоряжении LLM).

Figma plugin

bun run build:plugin                       # собрать плагин
poopseek --figma                           # запустить с авто-стартом Figma-сервера

В Figma Desktop: Plugins → Development → Import plugin from manifest → выбрать build/plugins/figma/manifest.json. После запуска PoopSeek будет слушать на http://localhost:7331.

Подробности pipeline (DSL, compile, edit-diff, plugin invariants, debug) — docs/articles/figma-pipeline.md.

🏗️ Архитектура

src/
├── agent/                    Agent loop, context-manager, tool-executor, sub-agent, streaming-tool-parser
├── cli/
│   ├── run-cli.ts            Тонкий orchestrator всех фаз загрузки
│   ├── bootstrap/            Изолированные фабрики фаз
│   │   ├── provider-bootstrap.ts   onboarding + createProvider
│   │   ├── version.ts              resolveAppVersion
│   │   ├── status-line.ts          bottom-bar renderer
│   │   ├── output-helpers.ts       detached output + user message
│   │   ├── figma-scope.ts          enter/exit/load Figma jam
│   │   ├── interrupts.ts           cancel + onGoHome
│   │   ├── session-helpers.ts      session save/start, provider reset
│   │   ├── context-sync.ts         MCP/Skills/Role/Poet → ContextManager
│   │   └── rag-bootstrap.ts        RAG controller (auto-index, status snapshot, model download)
│   ├── terminal-input.ts     Ввод с автокомплитом, paste-блоками
│   ├── views/                LoadingView, ChoiceView, ConfirmView, SkillsView
│   └── ...                   onboarding, runtime-config, session-store, file-mentions, sidechat, ...
├── commands/
│   ├── handlers.ts           buildCommandHandlers — общий map
│   ├── defs/
│   │   ├── mcp/              Подкоманды /mcp: status, listings, lifecycle, info, content
│   │   ├── acp/              Подкоманды /acp: status, registry, lifecycle, send, proxy, sessions, config
│   │   ├── figma/            Подкоманды /figma
│   │   └── <name>.ts         Простые команды (по одной на файл)
│   └── ...
├── providers/
│   ├── index.ts              PROVIDER_IDS + createProvider() factory
│   ├── defaults.ts           Единый источник UI-дефолтов провайдеров
│   ├── deepseek-web.ts       DeepSeek через src/deepseek-client/
│   ├── openai-compat.ts      OpenAI / OpenRouter / HuggingFace / Ollama / LM Studio
│   ├── anthropic.ts          Claude
│   └── gemini.ts             Gemini
├── deepseek-client/          Нативный клиент DeepSeek web (PoW, sessions, file upload)
├── tools/
│   ├── defs/                 31+ tool: file.*, bash, powershell, git, memory.*, user.*, agent.*, todo.*, skill.read
│   ├── index.ts              toolsRegistry
│   └── utils/                memory-path, todo-store, write-text-file
├── mcp/
│   ├── manager.ts            MCPManager (lifecycle, dynamic tool resolver, prompt-as-skill)
│   ├── sdk-utils.ts          encodeMCPToolName, withTimeout, toolResultToString
│   ├── transport.ts          stdio + Streamable HTTP factory
│   ├── status-cache.ts       5-min TTL skip-broken-server cache
│   ├── docs.ts               generateToolsDoc, buildResourcesContext, promptsAsSkills
│   ├── config.ts             auto-discovery (Claude Desktop, VS Code, Cursor, Trae)
│   └── types.ts
├── acp/
│   ├── server/               PoopseekAcpAgent + ACPSession + permission gate + client-proxies
│   ├── client/               ACPClient + ACPClientManager + proxy-tool
│   ├── config.ts             ~/.poopseek/acp.config.json
│   └── types.ts
├── rag/                      Codebase RAG: chunker, embedder, store (SQLite+FTS5), search, RRF, indexer
├── figma/
│   ├── server.ts             HTTP+SSE сервер для Figma-плагина (default port 7331)
│   ├── engine/jsx/
│   │   ├── jsx-compiler/     types/helpers/styles/frame/text/image/shapes/instance + dispatcher
│   │   ├── jsx-parser.ts     JSX → JsxNode[]
│   │   ├── jsx-validator.ts  + jsx-spec.ts (ALLOWED_TAGS, COMPONENT_SPECS)
│   │   ├── jsx-buffer.ts     in-memory tree для edit flow
│   │   ├── jsx-diff-applier.ts  partial-merge + `old` semantics + dup-key rejection
│   │   ├── jsx-key-mapper.ts    key="..." → id
│   │   └── token-resolver.ts    token name → value + variable binding
│   ├── engine/theme/         theme-state, design-md-parser
│   ├── infrastructure/http/handlers/chat/
│   │   ├── index.ts          handleChat orchestrator
│   │   ├── helpers.ts        looksLikeEdit, readPrompt, computeNextRootX, singleNodeJsx
│   │   ├── sse.ts            createSseResponse, makeSender
│   │   ├── vision.ts         evaluateVision
│   │   ├── intent.ts         resolveIntent (edit keyword → brief → enhance cache / LLM)
│   │   ├── create-flow.ts    designer → builder → validate → compile
│   │   ├── edit-flow.ts      handyman LLM → diff → emit ops
│   │   ├── edit-diff.ts      diffBufferSnapshots + emitSurgicalOps + emitWipeRecreateOps
│   │   └── legacy.ts         non-SSE JSON fallback
│   └── application/pipeline/ designer, builder, handyman, componentize, intent
├── skills/                   SkillManager + 49+ skill folders
├── roles/                    Roles (alternative persona prompts)
├── stores/                   ProviderStore / SessionStore / ConfigStore / CallOptionsStore
├── variables/                Подстановка переменных в промпты
├── bridge/                   Stream parsers для DeepSeek
├── logger.ts                 Логгер (с ACP-server file-output)
├── paths.ts                  Единый источник filesystem-локаций
└── index.ts                  Entry

plugins/figma/                Сам Figma plugin
├── src/
│   ├── code.ts               Entry
│   ├── handlers.ts           EXECUTE_OPS dispatcher
│   ├── ops/                  Per-op handlers (create-frame, create-text, set-fill, ...)
│   ├── helpers/              logical-id / color / font / node-to-jsx / snapshot / variables / text-styles / token-binding / paint-layout
│   ├── cache.ts              nodeMap, collectionCache, colorVariableCache, ...
│   ├── debug.ts              dlog/derr + log buffer card
│   └── types.ts              FigmaOp union + plugin contracts
├── ui.html / ui.css          UI iframe (CSS inlined at build time)
├── manifest.json
└── build.ts                  esbuild script

Filesystem layout

Все пути живут в src/paths.ts. Никогда не хардкодить path.join(os.homedir(), ".poopseek", …) в callsite — добавляй константу.

Корень	Описание
`POOPSEEK_HOME = ~/.poopseek`	sessions, memories, jams, roles, ACP config + log, skill folders, thesvg index
`POOPSEEK_APPDATA = APPDATA/poopseek` (Win) / `~/.config/poopseek` (POSIX)	runtime config.json, file-id-cache, MCP status cache, figma-sessions
`APPDATA_ROOT`	sibling tools' config dirs (Claude Desktop, VS Code, Cursor, Trae) для MCP discovery

⚙️ Конфигурация

.env — токены провайдеров (DEEPSEEK_TOKEN, OPENAI_API_KEY, ANTHROPIC_API_KEY, …)
RUNTIME_CONFIG_FILE — provider, configuredProviders, userName, onboardingDone, modelVariant
mcp.config.json (в рабочей папке) — конфиг MCP-серверов
~/.poopseek/acp.config.json — ACP-агенты + permission policy

Переменные в промптах

Синтаксис {{variableName}}. Реализация в src/variables/. Доступны:

{{workspaceRoot}} — текущая папка
{{userName}} — имя пользователя
{{files}} — список файлов
{{os}} — операционная система
{{isGitAvailable}} — наличие git

🧪 Разработка

Всегда используй bun / bunx, никогда npm / npx / yarn. Проект работает на Bun runtime с bun.lock как lockfile. npm install сломает lockfile-консистентность.

Сборка / проверки

bun start                # запуск в dev-режиме
bun run check            # tsc --build (проверка типов)
bun run test             # vitest run (НЕ `bun test` — это встроенный runner, не vitest)
bun run build:windows    # exe для Windows
bun run build:macos      # macOS
bun run build:plugin     # Figma plugin

Git pre-commit guardrail

Установлен husky-хук .husky/pre-commit — каждый коммит сначала прогоняет bun run check (tsc) + bun run test (vitest). На свежем checkout bun install сам активирует хук через prepare script. Если действительно нужно закоммитить WIP с поломкой — git commit --no-verify.

Добавление нового инструмента

Создай src/tools/defs/<name>.ts с export const name = "..." и export const handler: ToolHandler = ...
Зарегистрируй в src/tools/index.ts (импорт + добавление в toolsRegistry)
Опционально: добавь описание в assets/prompts/tools.prompt.md для LLM

Добавление новой подкоманды `/mcp` или `/acp`

Создай src/commands/defs/mcp/<sub>.ts (или acp/) с export function handleX(...) или export async function handleX(...)
Заведи ветку в switch внутри src/commands/defs/mcp/index.ts (или acp/index.ts)

Не наращивай dispatcher: каждый sub — отдельный файл.

Добавление новой фазы CLI bootstrap

Создай src/cli/bootstrap/<phase>.ts с factory create*(deps): Api
Вызови её в src/cli/run-cli.ts в подходящей точке композиции (стиль const { foo, bar } = createX({ ... }))

Отладка Figma plugin

Toggle DEBUG = true в plugins/figma/src/debug.ts. После каждого EXECUTE_OPS батча в UI-карточке появится trace. Теги: [ops/N/M] [resolveParent] [resolveNode] [applyLayoutSizing] [set_auto_layout] [create_frame|text|rect|ellipse|image|line] [clear_frame_children] [ctx]. Первый ❌ ≈ root cause.

📦 Технологии

Runtime: Bun — JavaScript runtime + сборщик
Язык: TypeScript 5+ strict mode
MCP SDK: @modelcontextprotocol/sdk@1.29.0
ACP SDK: @zed-industries/agent-client-protocol@0.4.5
CLI: terminal-kit + кастомный input controller
Figma plugin: esbuild → target: ES2017 (sandbox-ограничение)

🤝 Вклад

Форк → ветка для фичи
PR с описанием

Перед PR:

bun run check (typecheck)
bun test (vitest)
Если правишь Figma plugin — bun run build:plugin (esbuild)

📄 Лицензия

Private — личное использование.

🐛 Известные ограничения

Bash на Windows: WSL или Git Bash
Figma plugin target — ES2017 (sandbox), Array.prototype.at, String.prototype.replaceAll и др. недоступны внутри плагина
Plugin использует classic moduleResolution — импорт barrel-файлов через явный суффикс from "../helpers/index"

📞 Поддержка

При проблемах:

Проверь токены провайдеров (/auth)
Bun установлен (bun --version)
bun install для обновления зависимостей
bun run check — проверка типов часто подсказывает регрессии после правок

PoopSeek — твой персональный CLI-агент. 🚀

Name		Name	Last commit message	Last commit date
Latest commit History 247 Commits
.github/workflows		.github/workflows
.husky		.husky
.trae/rules		.trae/rules
assets		assets
docker		docker
docs		docs
plugins/figma		plugins/figma
scripts		scripts
src		src
tests		tests
.env.example		.env.example
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md
bun.lock		bun.lock
install.ps1		install.ps1
install.sh		install.sh
package.json		package.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Folders and files

Latest commit

History

Repository files navigation

PoopSeek

✨ Особенности

🚀 Установка

Готовый бинарник (рекомендуется)

Из исходников (для разработки)

Сборка локально

Релиз через GitHub Actions

🎮 Использование

Интерактивный режим

Slash-команды

MCP-серверы

ACP

Figma plugin

🏗️ Архитектура

Filesystem layout

⚙️ Конфигурация

Переменные в промптах

🧪 Разработка

Сборка / проверки

Git pre-commit guardrail

Добавление нового инструмента

Добавление новой подкоманды /mcp или /acp

Добавление новой фазы CLI bootstrap

Отладка Figma plugin

📦 Технологии

🤝 Вклад

📄 Лицензия

🐛 Известные ограничения

📞 Поддержка

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 3

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Добавление новой подкоманды `/mcp` или `/acp`

Packages