{"id":50931961,"url":"https://github.com/forbidden0005/project-iceberg","last_synced_at":"2026-06-17T05:04:36.098Z","repository":{"id":357235391,"uuid":"1235200413","full_name":"Forbidden0005/Project-Iceberg","owner":"Forbidden0005","description":"Local-first AI assistant with Multi-LLM backends, MCP tool servers, autonomous execution. Web UI + CLI. What you see is just the tip of the iceberg.","archived":false,"fork":false,"pushed_at":"2026-05-11T23:05:49.000Z","size":124,"stargazers_count":0,"open_issues_count":3,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-12T00:24:13.047Z","etag":null,"topics":["agent","agent-orchestration","ai-assistant","ai-coding","anthropic","automation","contrib","contributions-welcome","flask","help","help-wanted","llm","local","local-ai","looking-for-contributors","mcp","needs-review","ollama","python","self-hosted"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Forbidden0005.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-11T05:25:58.000Z","updated_at":"2026-05-11T23:05:53.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Forbidden0005/Project-Iceberg","commit_stats":null,"previous_names":["forbidden0005/project-iceberg"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/Forbidden0005/Project-Iceberg","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Forbidden0005%2FProject-Iceberg","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Forbidden0005%2FProject-Iceberg/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Forbidden0005%2FProject-Iceberg/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Forbidden0005%2FProject-Iceberg/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Forbidden0005","download_url":"https://codeload.github.com/Forbidden0005/Project-Iceberg/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Forbidden0005%2FProject-Iceberg/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34434497,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-17T02:00:05.408Z","response_time":127,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent","agent-orchestration","ai-assistant","ai-coding","anthropic","automation","contrib","contributions-welcome","flask","help","help-wanted","llm","local","local-ai","looking-for-contributors","mcp","needs-review","ollama","python","self-hosted"],"created_at":"2026-06-17T05:04:21.729Z","updated_at":"2026-06-17T05:04:36.088Z","avatar_url":"https://github.com/Forbidden0005.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n```\n ___           _           _     ___          _                   \n| _ \\_ _ ___ (_)___ _ ___| |_  |_ _|__ ___| |__  ___ _ _ __ _ \n|  _/ '_/ _ \\| / -_) / / _` |   | |/ _/ -_) '_ \\/ -_) '_/ _` |\n|_| |_| \\___// \\___\\_\\_\\__,_|  |___\\__\\___|_.__/\\___|_| \\__, |\n           |__/                                          |___/ \n```\n\n# 🧊 Project Iceberg\n\n*Local-first AI assistant with multi-LLM support and MCP extensibility*\n\n**What you see is just the tip of the iceberg.**\n\n\u003c/div\u003e\n\n---\n\n## Quick Start\n\n### Web UI (Recommended)\n\n**Windows:**\n```bash\nLaunch.bat\n```\n\n**Mac/Linux:**\n```bash\npip install -r requirements.txt\npython server.py\n```\n\nOpens browser at `http://localhost:5000` with a chat interface. Includes:\n- One-click MCP server installation\n- Voice mode support\n- Tool usage visualization\n- LLM provider switching\n\n### Command Line\n\n```bash\npip install -r requirements.txt\npython main.py\n```\n\nNo configuration needed. On startup it auto-detects whichever LLM backend is running:\n\n1. **LM Studio** (`http://localhost:1234`) — local, OpenAI-compatible\n2. **Ollama** (`http://localhost:11434`) — local\n3. **Anthropic** (cloud) — if `ANTHROPIC_API_KEY` is set\n\nIf nothing is reachable, it falls back to regex-only mode and still runs tool commands.\n\n## MCP (Model Context Protocol) Support\n\nProject Iceberg supports MCP servers for extended functionality. The web UI includes a one-click installer for popular MCP servers:\n\n- **Filesystem** — Local file operations\n- **Memory** — Persistent knowledge graph\n- **Fetch** — Web content retrieval\n- **GitHub** — Repository management (requires API key)\n- **PostgreSQL/SQLite** — Database access\n- **Puppeteer** — Browser automation\n- And more...\n\nMCP servers require Node.js/npx. The launcher checks dependencies automatically.\n\n## How natural language works\n\nEvery user turn goes through three stages:\n\n```\nyou type something\n      |\n      v\n  [Dispatcher]  ---\u003e  classify: chat | tools | mixed\n      |\n      +-- chat:   LLM answers conversationally\n      +-- tools:  LLM plans tool calls, executor runs them\n      +-- mixed:  tools run, then LLM narrates the result\n```\n\nSo things like:\n\n| You say | What happens |\n|---|---|\n| `hey what's up` | Chat reply |\n| `explain async in python` | Chat reply |\n| `list my downloads folder` | Runs `list_dir(~/Downloads)` |\n| `what's in this directory?` | Runs `list_dir(.)` |\n| `make a note called ideas.txt` | Runs `create_file(ideas.txt)` |\n| `scan my desktop and tell me what looks old` | Runs scan + LLM narrates |\n\nThe conversation has memory, so this works:\n```\n\u003e what's in my home folder?\n  \u003clist appears\u003e\n\u003e and how big is the Downloads one?\n  \u003cthe model knows \"the Downloads one\" refers to Downloads in your home\u003e\n```\n\n## Configuration\n\n**Environment variables** (simplest):\n```bash\n# Force a specific backend\nAI_ASSISTANT_PROVIDER=lmstudio\nLMSTUDIO_MODEL=qwen2.5-coder-7b\n\n# Or use Anthropic\nANTHROPIC_API_KEY=sk-ant-...\n```\n\n**Or** copy `config.example.json` to `config.json` and edit.\n\n## Commands\n\n- `help` — show this\n- `tools` — list available tools\n- `status` — show which LLM is active and history length\n- `reset` — clear conversation history\n- `exit` or `quit` — leave\n\nEverything else is natural language.\n\n## Architecture\n\n```\nmain.py\n  |\n  OrchestratorAgent\n    |-- Dispatcher       classify intent (chat|tools|mixed)\n    |-- Planner          tool calls from natural language (LLM or regex)\n    |-- Executor         safety-gated tool dispatch\n    |     |-- FileAgent     file/scan tools\n    |     |-- SystemAgent   web/sysinfo/plugin tools\n    |-- SafetyManager    policy.json: allow|confirm|deny per tool\n    |-- ShortMemory      rolling deque of recent turns\n    |-- LongMemory       JSON + cosine-similarity recall\n    |-- LLM provider     auto-detected: lmstudio|ollama|anthropic\n    |\n  AutomationEngine       runs workflows on a timer\n  Scheduler              threaded, ticks the engine\n```\n\n## Safety\n\n`safety/policy.json` (auto-created):\n\n| tool | rule |\n|---|---|\n| list_dir, scan, read_file, web_search | allow |\n| create_file, delete_file, move_file | confirm |\n| run_shell | deny |\n\nConfirm asks `y/N` before running. In non-interactive mode it denies (fail-closed). Edit the JSON to change. Since the LLM can now propose destructive ops freely from natural language, these gates matter more than before.\n\n## Plugins\n\nDrop a Python file in `tools/plugins/`:\n\n```python\ndef hello(name: str = \"world\"):\n    return f\"hi {name}\"\n\ndef register(registry):\n    registry.register(\n        \"hello\", hello,\n        description=\"Say hi.\",\n        category=\"system\",\n        args=[{\"name\": \"name\", \"required\": False, \"description\": \"Who to greet.\"}],\n    )\n```\n\nLoaded automatically on startup. The `args` schema is what the LLM reads when deciding how to call your tool.\n\n## Workflows\n\n```json\n{\n  \"name\": \"cleanup_temp\",\n  \"interval\": 10,\n  \"condition\": \"file_exists temp.txt\",\n  \"actions\": [\"delete file temp.txt\"]\n}\n```\n\nDrop in `workflows/`. Conditions: `always`, `never`, `file_exists \u003cpath\u003e`, `file_missing \u003cpath\u003e`.\n\n## Tests\n\n```bash\npython -m unittest discover tests\n```\n\n46 tests covering planner, dispatcher, auto-detect, memory, safety, scan, file tools, workflows.\n\n## Layout\n\n```\nagent_core/    logger, LLM providers, dispatcher\nagents/        orchestrator + sub-agents\nautomation/    workflow engine\nexecutor/      safety-gated tool dispatch\nmemory/        short + long-term memory\nplanner/       NL -\u003e tool calls\nsafety/        policy-based gating\ntools/         builtin tools, registry, plugins\nutils/         embedding\nvoice/         voice mode (optional)\nworkflows/     user workflow files\nlogs/          runtime log\ntests/         unit tests\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fforbidden0005%2Fproject-iceberg","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fforbidden0005%2Fproject-iceberg","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fforbidden0005%2Fproject-iceberg/lists"}