{"id":50205800,"url":"https://github.com/arrase/cud","last_synced_at":"2026-05-26T01:07:34.109Z","repository":{"id":355739457,"uuid":"1228352437","full_name":"arrase/cud","owner":"arrase","description":"An Openclaw-like assistant designed to be lightweight and intuitive.","archived":false,"fork":false,"pushed_at":"2026-05-21T23:42:09.000Z","size":2299,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-22T06:50:45.858Z","etag":null,"topics":["agentic-ai","deepagents","ollama","ollama-app"],"latest_commit_sha":null,"homepage":"https://arrase.github.io/cud/","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/arrase.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"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-03T23:17:09.000Z","updated_at":"2026-05-21T23:39:52.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/arrase/cud","commit_stats":null,"previous_names":["arrase/cud"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/arrase/cud","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arrase%2Fcud","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arrase%2Fcud/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arrase%2Fcud/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arrase%2Fcud/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/arrase","download_url":"https://codeload.github.com/arrase/cud/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arrase%2Fcud/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33499300,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-25T14:31:05.219Z","status":"ssl_error","status_checked_at":"2026-05-25T14:31:02.878Z","response_time":57,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["agentic-ai","deepagents","ollama","ollama-app"],"created_at":"2026-05-26T01:07:33.357Z","updated_at":"2026-05-26T01:07:34.094Z","avatar_url":"https://github.com/arrase.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🦙 Cud\n\n\u003e **Cud** (the bolus of food that llamas chew) is a local-first, multi-agent framework where **simplicity** is the ultimate foundation. \n\nDesigned to be lightweight, straightforward, and incredibly easy to use, Cud brings the power of autonomous AI agents directly to your local machine.\n\n---\n\n## ✨ Core Principles\n\n- 🎯 **Simplicity First**: No convoluted setups or bloated abstractions. Cud is built to be intuitive, readable, and easy to hack on.\n- 🔒 **Local \u0026 Private**: Powered by **[Ollama](https://ollama.com/)**, your data, prompts, and memory stay 100% on your machine.\n- 🤖 **Multi-Agent Architecture**: Create a fleet of specialized agents, each with its own persona, memory, and workspace.\n- 📖 **Transparent**: Agent behavior is defined in plain Markdown (`AGENT.md`). No hidden prompts, no black boxes.\n- 🛠️ **Tool-Rich**: Built-in support for persistent shell sessions, surgical filesystem operations, Custom SKILLs, and the Model Context Protocol (MCP).\n- 👻 **Daemon-Ready**: Seamlessly run your agents as background services using `systemd`.\n\n---\n\n## 🦙 Ollama \u0026 Tool Calling\n\nCud relies on **Ollama** for local inference. \n\n\u003e [!IMPORTANT]\n\u003e **Tool Calling Support is Required!**  \n\u003e Because Cud agents interact with your local environment (shell, filesystem, etc.), you **must** download and use models in Ollama that explicitly support **tool calling** (e.g., `gpt-oss:20b`, `gemma4:e4b`, `qwen3.6:27b`). \n\n---\n\n## 🚀 Quick Start\n\n### 1. Installation\n\n*Requires Python 3.11+ and a Linux distribution with systemd.*\n\nYou can install Cud automatically using our install script (requires `pipx` or `uv`):\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/arrase/cud/main/install.sh | bash\n```\n\n**Manual Installation:**\n\n```bash\npipx install --force git+https://github.com/arrase/cud.git\n# or\nuv tool install --force git+https://github.com/arrase/cud.git\n```\n\n### 2. Configure Ollama\n\nEnsure you have Ollama installed and a tool-calling capable model downloaded:\n\n```bash\nollama run gemma4:e4b\n```\n\n### 3. Create Your First Agent\n\n```bash\n# Create an agent named \"researcher\"\ncud agent create researcher\n\n# Configure it to use a specific model with tool calling support\ncud agent config researcher --model gemma4:e4b\n\n# Setup your Discord token\ncud gateway setup researcher discord --token YOUR_BOT_TOKEN\n```\n\n### 4. Run the Agent (Discord Gateway)\n\n```bash\n# Start it as a background service\ncud gateway start researcher\n```\n\n### 5. Local Terminal Interface (TUI)\n\nYou can also interact with your agent locally through a rich terminal interface.\n\n```bash\n# Start the local chat REPL\ncud tui researcher\n```\n\nInside the TUI, type `/help` to see available commands, or `/quit` to exit.\n\n### 6. Desktop Graphical User Interface (GUI)\n\nCud includes a powerful desktop application to manage your agents, monitor their memory, and configure tools interactively.\n\n```bash\n# Start the desktop GUI\ncud-gui\n```\n\n![Dashboard](screenshots/dashboard.png)\n\n---\n\n## 💬 Discord Commands\n\nWhen interacting with your agent via the Discord Gateway, you can use the following slash commands:\n\n- `/new`: Start a new Cud session in the current Discord thread (clears context history).\n- `/model \u003cmodel_name\u003e`: Temporarily switch the agent's configured model.\n- `/usage`: Show Cud runtime usage summary (agent name, current model, and thread ID).\n- `/undo`: Remove the last exchange from the current thread.\n- `/reload`: Reload tools and the system prompt (`AGENT.md`) for this agent.\n- `/memory view`: View the contents of the agent's long-term `MEMORY.md`.\n- `/memory clear`: Clear the agent's long-term `MEMORY.md`.\n\n---\n\n## 🧠 Key Concepts\n\n### 📂 Agents \u0026 Workspaces\nEvery agent lives in `~/.cud/agents/\u003cname\u003e/`. This directory contains its entire \"soul\":\n- ⚙️ `settings.yaml`: Model parameters and tool configurations.\n- 🎭 `AGENT.md`: The system prompt—defining its persona and rules.\n- 📝 `MEMORY.md`: Long-term memory that the agent can read and update.\n- 💾 `history.db`: A SQLite-backed checkpointer for conversation state.\n- 🔌 `mcp.json`: MCP server configurations.\n- 💻 `workspace/`: The dedicated directory where the agent runs commands and edits files.\n- 🧰 `workspace/skills/`: A directory for custom Markdown-defined abilities.\n\n![General Configuration](screenshots/general.png)\n![Agent Instructions](screenshots/instructions.png)\n![Memory Management](screenshots/menory.png)\n\n### 🪄 Skills (`SKILL.md`)\nSkills are portable sets of instructions and tools. Just drop a folder with a `SKILL.md` into an agent's `workspace/skills/` directory, and it instantly gains those capabilities.\n\n![Skills Management](screenshots/skills.png)\n\n### 🗜️ Context Compression\nTo keep agents fast and prevent them from hitting token limits during long conversations, Cud features automatic context compression.\n- **Automatic Summarization**: When a conversation gets too long, older messages are automatically summarized by the LLM.\n- **No Data Lost**: The full, uncompressed conversation history is safely offloaded to a markdown file in the agent's workspace (`workspace/conversation_history/\u003cthread_id\u003e.md`).\n- **Manual Compaction**: Agents have access to a `compact_conversation` tool, allowing them to proactively free up context when finishing a large task.\n\n### ⏱️ Periodic Tasks\nAgents can execute scheduled, periodic tasks autonomously. Tasks are defined as Markdown files (`TASK.md`) located in the agent's `workspace/tasks/\u003cname\u003e/` directory.\n- Use a YAML frontmatter to configure the `schedule` (cron expression) and the destination (`channel_id` or `user_id`).\n- The rest of the file is the prompt the agent executes.\n- Ask your agent to create tasks for you, or edit them manually.\n- Use the `/reload` command in Discord to activate changes.\n- Check active tasks via the CLI: `cud task list \u003cagent\u003e`.\n\n**Example: `workspace/tasks/daily-news/TASK.md`**\n```markdown\n---\nname: \"Daily Tech News\"\ndescription: \"Searches for latest AI news and summarizes it\"\nschedule: \"0 9 * * *\"\nchannel_id: 123456789012345678\nenabled: true\n---\n\nSearch the web for the latest AI news.\nSummarize the top 3 stories.\nMake it sound enthusiastic!\n```\n\n![Periodic Tasks](screenshots/tasks.png)\n\n### 🌐 Model Context Protocol (MCP)\nNative support for MCP allows you to connect your agents to external tool servers (e.g., Brave Search, GitHub, Google Drive) with a single command.\n\nFor HTTP/SSE servers:\n```bash\ncud mcp add researcher https://mcp-server.example.com/sse --name search\n```\n\nFor stdio servers (with arguments and environment variables):\n```bash\ncud mcp add researcher \"npx -y @modelcontextprotocol/server-postgres postgresql://localhost/mydb\" \\\n    --name db-search \\\n    --env POSTGRES_PASSWORD=secret\n```\n\n![MCP Servers](screenshots/mcp.png)\n\n### 🤖 Custom Subagents\nDefine specialized subagents that your main agent can delegate tasks to. Each subagent has its own isolated context, skills, and MCP servers — keeping the orchestrator's context clean and focused.\n\nConfigure them in `settings.yaml`:\n```yaml\nsubagents:\n  - name: \"research-agent\"\n    description: \"Delegate here for complex research or web searches.\"\n    system_prompt: \"You are a research specialist. Search thoroughly and return concise summaries.\"\n    model: \"gemma4:e4b\"  # Optional, inherits from main agent\n    context_window: 65536  # Optional, inherits from main agent\n    skills_paths:\n      - \"./workspace/skills/research\"\n    mcp_servers:\n      - name: \"brave-search\"\n        command: \"npx\"\n        args: [\"-y\", \"@modelcontextprotocol/server-brave-search\"]\n        env:\n          BRAVE_API_KEY: \"${BRAVE_API_KEY}\"\n\n  - name: \"database-agent\"\n    description: \"Delegate here when the user asks about customer or sales data.\"\n    system_prompt: \"You are a database analyst. Query the database and summarize results.\"\n    skills_paths:\n      - \"./workspace/skills/database\"\n    mcp_servers:\n      - name: \"sqlite-server\"\n        command: \"uvx\"\n        args: [\"mcp-server-sqlite\", \"--db-path\", \"./data/ventas.db\"]\n```\n\n- **Context isolation**: Subagent tool calls don't bloat the main agent's context — only the final result is returned.\n- **Environment injection**: Use `${VAR_NAME}` in MCP `env` fields to inject secrets from the host environment.\n- **Graceful failures**: If a subagent's MCP server fails to load (e.g., missing env vars), it is skipped and the agent continues normally.\n\n![Subagents](screenshots/subagents.png)\n\n---\n\n## 🏗️ Architecture\n\nCud is built on a robust, modular stack:\n- **Orchestration**: [DeepAgents](https://docs.langchain.com/oss/python/deepagents/overview) provides the stateful, cyclic reasoning loops.\n- **LLM Engine**: [Ollama](https://ollama.com/) powers the local inference with tool calling capabilities.\n\n---\n\n## 🛠️ Development\n\nTo set up a local development environment:\n\n```bash\n# Clone the repository\ngit clone https://github.com/arrase/cud.git\ncd cud\n\n# Create and activate a virtual environment\npython -m venv .venv\nsource .venv/bin/activate\n\n# Install development dependencies\npip install -e .\n```\n\n---\n\n## 📜 License\n\nMIT License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farrase%2Fcud","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Farrase%2Fcud","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farrase%2Fcud/lists"}