{"id":49496514,"url":"https://github.com/almide/homullus","last_synced_at":"2026-05-01T10:00:27.011Z","repository":{"id":354968630,"uuid":"1226223046","full_name":"almide/homullus","owner":"almide","description":"Modular AI agent CLI runtime, written in Almide — the language LLMs write, made flesh.","archived":false,"fork":false,"pushed_at":"2026-05-01T08:02:34.000Z","size":27,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-01T08:27:13.320Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":null,"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/almide.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-01T05:46:48.000Z","updated_at":"2026-05-01T08:02:17.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/almide/homullus","commit_stats":null,"previous_names":["almide/homullus"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/almide/homullus","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/almide%2Fhomullus","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/almide%2Fhomullus/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/almide%2Fhomullus/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/almide%2Fhomullus/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/almide","download_url":"https://codeload.github.com/almide/homullus/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/almide%2Fhomullus/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32492594,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-30T13:12:12.517Z","status":"online","status_checked_at":"2026-05-01T02:00:05.856Z","response_time":64,"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":[],"created_at":"2026-05-01T10:00:22.546Z","updated_at":"2026-05-01T10:00:27.005Z","avatar_url":"https://github.com/almide.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# homullus\n\n**Modular AI agent CLI runtime, written in [Almide](https://github.com/almide/almide).**\n\n\u003e *homullus* — Latin diminutive of *homo*: a small, made human. Almide is the language LLMs write; *homullus* is what the language writes into existence: a precise, autonomous agent that reads, writes, and runs your code.\n\n```bash\n# Pick any tool-calling provider (groq is free-tier, OpenAI-compatible)\nexport GROQ_API_KEY=gsk_...\nMODEL=groq/llama-3.3-70b-versatile almide run src/main.almd\n```\n\n```\nhomullus v0.0.1\nmodel: groq/llama-3.3-70b-versatile    trust: default    /help for commands\n\n\u003e list the .almd files in src/ using a tool\n[Bash] {\"command\":\"ls /abs/src/*.almd\"}\n[b2vcvddjg] /abs/src/agent_check.almd\n                  /abs/src/agent.almd\n                  /abs/src/main.almd\n                  ...\n\n\u003e /model anthropic/claude-sonnet-4-6\nModel set to: anthropic/claude-sonnet-4-6\n```\n\nEnd-to-end run captured: [`docs/dogfooding-2026-05-01.md`](docs/dogfooding-2026-05-01.md) — a real LLM driving Read + Edit through homullus's tool runtime, no human in the loop.\n\n## Why homullus\n\nThe agent loop is small but it's the densest IO surface in any almide program: HTTP, fs, process, json, REPL, structured tool dispatch, recursive state. Building it in Almide does two things at once:\n\n1. **Real, daily-driver agent** built on [`almai`](https://github.com/almide/almai) — multi-provider, no Anthropic-only lock-in.\n2. **Pressure test** for the language. Wherever the implementation strains, the friction goes back upstream as a stdlib gap, a diagnostic improvement, or a new idiom for the cheatsheet.\n\nIt is also a deliberate alternative to [Aid-On/famulus](https://github.com/Aid-On/famulus) (TypeScript). Same shape, different substrate.\n\n## Features (v0.0.1)\n\n- **REPL** with slash commands (`/model`, `/tools`, `/trust`, `/clear`, `/help`, `/exit`)\n- **6 built-in tools** — Bash, Read, Write, Edit, Glob, Grep\n- **Multi-provider** via almai — Anthropic, OpenAI, OpenRouter, Groq, Cloudflare, Azure, Google, Bedrock, Claude CLI\n- **3 permission modes** — `default` (read auto, others ask) · `accept-edits` (read+write auto) · `bypass` (everything auto)\n- **Dangerous-pattern detection** for Bash (`rm -rf`, `curl | sh`, `mkfs`, fork bombs) — confirmed even in `bypass`\n- **Retry with exponential backoff** on 429/5xx (via `almai.call_retry`)\n- **Native tool roundtrip** — `assistant.tool_calls` ↔ `role:\"tool\"` with `tool_call_id`, working across every almai-supported provider that exposes tool calls\n- **Provider injection** for testing — `agent.run_turn` accepts any `(model, msgs, opts) -\u003e Result[LLMResponse, String]` callable, so tests use scripted responses without API keys\n- **Smoke test** — `almide run src/smoke.almd` round-trips a real LLM call without a REPL\n- **Integration check** — `almide run src/agent_check.almd` exercises 24 assertions across tool roundtrip / multi-round loop / history threading / provider error / no-tool path\n\n## Verified end-to-end\n\n| Provider             | Tool calls | Verified |\n|----------------------|:---:|:---:|\n| `groq/`              | ✅  | dogfooding 2026-05-01 (Read + Edit, [log](docs/dogfooding-2026-05-01.md)) |\n| `cf/`                | ❌  | text-only (provider doesn't expose tool calls) |\n| `cli/claude`         | ❌  | turnkey-agent (Claude Code dispatches its own tools) |\n| `anthropic/`, `openai/`, `openrouter/`, `azure/`, `bedrock/`, `google/` | ✅ wire | covered by `almai`'s wire-format tests, no API keys at hand to run end-to-end |\n\n## Layout\n\n```\nhomullus/\n├── almide.toml          package = homullus, deps: almai\n├── src/\n│   ├── main.almd        REPL, slash commands, state threading\n│   ├── agent.almd       single-turn query + tool loop\n│   ├── tools.almd       Bash/Read/Write/Edit/Glob/Grep dispatch\n│   ├── permission.almd  3-mode resolver + dangerous patterns\n│   ├── smoke.almd       non-interactive end-to-end check (1 round-trip)\n│   └── agent_check.almd 24 integration assertions w/ scripted providers\n└── README.md\n```\n\n`main.almd` is a conductor. State (model / mode / history / system prompt) is threaded through a recursive REPL — no globals, no mutability outside a single `run_turn`.\n\n## Install\n\nRequires [Almide](https://github.com/almide/almide) at the develop tip (PRs #231–#235 are required for cross-package codegen and JSON unicode handling). The next tagged release will include all of these.\n\n```bash\ngit clone https://github.com/almide/homullus.git\ncd homullus\nalmide test                       # 5 unit tests pass\nalmide run src/agent_check.almd   # 24 integration assertions pass\nalmide run src/main.almd          # interactive REPL\n```\n\nFor a binary install (planned, once `[[bin]]` lands in `almide.toml`):\n\n```bash\nalmide build src/main.almd -o ~/.local/bin/homu\nhomu\n```\n\n## Slash commands\n\n| Command            | Description |\n|--------------------|-------------|\n| `/model [spec]`    | Show or set model. Format: `provider/model` (e.g. `anthropic/claude-sonnet-4-6`, `openai/gpt-4o-mini`, `openrouter/meta-llama/llama-3.3-70b-instruct`) |\n| `/tools`           | List available tools |\n| `/trust [mode]`    | Permission mode: `default` / `accept-edits` / `bypass` |\n| `/clear`           | Clear conversation history |\n| `/help`            | Show commands |\n| `/exit`            | Exit |\n\nEnvironment overrides at startup: `MODEL`, `HOMU_TRUST`.\n\n## Roadmap\n\n### v0.1.0\n- Streaming text deltas (HTTP streaming intrinsic in almide stdlib + SSE parsers in almai providers)\n- Token usage display in REPL prompt\n- CLAUDE.md / git status auto-injection into the system prompt\n\n### v0.2.0\n- Auto-compact (token estimation + LLM summary at threshold)\n- Output filtering (rtk-style) for `git status` / `npm install` / test output\n- Session persistence (serialize/restore JSON, `/resume`)\n- Memory integration (MEMORY.md + relevance search)\n\n## License\n\nMIT / Apache-2.0\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falmide%2Fhomullus","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falmide%2Fhomullus","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falmide%2Fhomullus/lists"}