{"id":49845638,"url":"https://github.com/chozzz/vargos","last_synced_at":"2026-06-15T01:07:18.248Z","repository":{"id":342713856,"uuid":"1165425198","full_name":"chozzz/vargos","owner":"chozzz","description":"Self-hosted agent OS. Persistent memory, multi-channel presence, tools, scheduling, and sub-agent orchestration — any LLM, your hardware.","archived":false,"fork":false,"pushed_at":"2026-06-07T12:13:55.000Z","size":6780,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-07T14:09:58.137Z","etag":null,"topics":["ai-agent","llm","local-first","mcp","runtime","telegram","typescript","websocket","whatsapp"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/chozzz.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":"docs/ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-02-24T06:35:54.000Z","updated_at":"2026-06-07T12:13:22.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/chozzz/vargos","commit_stats":null,"previous_names":["chozzz/vargos"],"tags_count":23,"template":false,"template_full_name":null,"purl":"pkg:github/chozzz/vargos","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chozzz%2Fvargos","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chozzz%2Fvargos/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chozzz%2Fvargos/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chozzz%2Fvargos/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/chozzz","download_url":"https://codeload.github.com/chozzz/vargos/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chozzz%2Fvargos/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34343381,"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-14T02:00:07.365Z","response_time":62,"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":["ai-agent","llm","local-first","mcp","runtime","telegram","typescript","websocket","whatsapp"],"created_at":"2026-05-14T11:03:52.252Z","updated_at":"2026-06-15T01:07:18.242Z","avatar_url":"https://github.com/chozzz.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Vargos\n\n**Self-hosted agent OS.** Give any LLM persistent memory, multi-channel presence, tools, scheduling, and sub-agent orchestration — all on your hardware.\n\n## What It Does\n\n- **Any LLM** — Anthropic, OpenAI, Google, OpenRouter, Ollama, LM Studio, Groq, Together, DeepSeek, Mistral, Fireworks, Perplexity\n- **Multi-channel presence** — connect WhatsApp and Telegram bots, route messages to the agent\n- **Automatic tool discovery** — every service feature becomes available as an agent tool\n- **MCP integration** — expose your agent's tools to other applications, connect external tool servers\n- **Persistent memory** — vector + keyword search across workspace files and conversation history\n- **Scheduled tasks** — run agent tasks on a schedule, send results to channels\n- **Webhooks** — trigger agent tasks from external systems (GitHub, monitoring, etc.)\n- **Subagent delegation** — agents can spawn child agents for parallel or hierarchical work\n- **Media intelligence** — images and audio handled automatically (vision, transcription)\n\n## Quick Start\n\n```bash\n# npx (no install)\nnpx @chozzz/vargos\n\n# or clone + run\ngit clone https://github.com/chozzz/vargos.git\ncd vargos\npnpm install\npnpm start\n```\n\nFirst run launches an interactive setup wizard (provider, model, API key). Config is saved to `~/.vargos/`.\n\nAfter setup: `vargos start` boots the server, `vargos onboard` re-runs the wizard, `vargos config` shows current settings.\n\n## Architecture\n\nOne **bus** owns one **registry** of methods. The CLI, the agent's tools, and the JSON-RPC\nserver are all projections of that registry — register a method once, it appears everywhere.\n\n```\n        CLI            Agent tools        JSON-RPC :9000\n          \\                 |                   /\n           └──────────  Bus (registry)  ───────┘\n                              │\n   config · log · web · memory · media · agent · channel · cron · mcp\n       (services/\u003cname\u003e/ — discovered from disk, loaded by the bus)\n```\n\nServices are isolated — no shared state, no cross-imports; they talk only via `bus.call` /\n`bus.emit`. See [Architecture](./docs/architecture.md).\n\n## Key Concepts\n\n- **Agent** — An AI system that reads instructions, sees available tools, and decides what to do to help you\n- **Channel** — A messaging platform (WhatsApp, Telegram) where users can talk to the agent\n- **System prompt** — Instructions that tell the agent how to behave (merged from `AGENTS.md`, `SOUL.md`, `TOOLS.md` in your workspace + per-channel persona files)\n- **Session** — A conversation thread with one user; Vargos remembers previous messages\n- **Tool** — A capability the agent can use (read a file, run code, fetch a URL, send a message)\n- **Workspace** — Your project folder where Vargos stores instructions, skills, and conversation history\n\n### Message Handling\n\nMessages go through a simple pipeline: **receive → process → execute → respond**. The agent has access to all Vargos tools and your workspace context. See [Usage](./docs/usage.md) for details.\n\n## Documentation\n\n| Doc | Description |\n|-----|-------------|\n| [Getting Started](./docs/getting-started.md) | Install, first run, config wizard |\n| [Configuration](./docs/configuration.md) | Full config reference |\n| [Architecture](./docs/architecture.md) | Bus registry, service contract, surfaces, hot reload |\n| [Usage](./docs/usage.md) | Channels, sessions, MCP, runtime, personas, workspace files |\n| [Extending](./docs/extending.md) | Add tools, skills, providers |\n| [Examples](./docs/examples.md) | MCP integration, scheduled research, multi-channel |\n| [Debugging](./docs/debugging.md) | Debug modes and logging |\n| [Roadmap](./docs/ROADMAP.md) | Planned features |\n\n## Usage\n\n```bash\nvargos                 # First-run wizard or help\nvargos start           # Boot the daemon (bus + all services + JSON-RPC :9000)\nvargos \u003cservice\u003e       # List a service's methods (e.g. vargos channel)\nvargos \u003cservice\u003e --help        # Methods, descriptions, arg shapes\nvargos \u003cservice\u003e \u003cmethod\u003e …    # Invoke a method (e.g. vargos channel send \u003cto\u003e \"\u003cmsg\u003e\")\nvargos onboard         # Re-run setup wizard\n```\n\n## Development\n\n```bash\npnpm install          # Install deps\npnpm start            # Boot the daemon (alias: vargos start)\npnpm chat             # Pi SDK interactive REPL bound to ~/.vargos/agent\npnpm cli              # Run the CLI entrypoint directly (tsx cli.ts)\npnpm verify           # Run the core acceptance checks (scripts/verify-core.ts)\npnpm run test:run     # Tests (single run)\npnpm run typecheck    # TypeScript check\npnpm lint             # ESLint + typecheck\npnpm build            # Clean + compile + copy templates → dist/\n```\n\n## Contributing\n\nSee [CONTRIBUTING.md](./CONTRIBUTING.md) for architecture and development guidelines.\n\n## License\n\n[MIT](./LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchozzz%2Fvargos","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchozzz%2Fvargos","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchozzz%2Fvargos/lists"}