Agents Arwaky

💡 Executive Summary

Modern autonomous AI workflows demand dozens of polyglot toolchains—Rust (cargo), Node (pnpm/npm), Bun, Python (uv), Playwright headless browsers, and system C-libraries. Installing these natively clutters the host operating system, introduces version conflicts, and creates security vulnerabilities.

agents-arwaky solves this through a Local Bare-Metal Architecture:

• ⚡ Direct Host Execution: Compilers, dependencies, and runtimes are installed natively on the host. Tools compile to host-native binaries in ~/.local/bin/ via standard Linux XDG integration. Run tools from your host terminal directly.
• 🤖 Universal MCP Hub & Skills Provisioner: Out-of-the-box integration for AI harnesses (Google Antigravity, Hermes Agent with full multi-profile sync, OpenCode, Cursor, Zed) via declarative MCP configs and automated skill provisioning.
• 🎯 Unified Orchestration (agents-arwaky / aa CLI): One single control point for diagnostics, health checks, execution dispatching, and build pipelines.
• 🐳 Daemon-only Containerization: Only background daemons (9Router, Anytype) run in Podman containers. CLI tools and MCPs are host-native.

📑 Table of Contents

• Architecture
  • System Flow
  • Directory Layout
• Quickstart in 60 Seconds
• Unified Orchestrator CLI (agents-arwaky / aa)
• Agent & Tool Catalog
  • Core In-House Agents (internal/)
  • Curated Upstream Vendor Tools (vendor/)
• MCP Client Integration
  • Anytype Headless Daemon
  • Automated Harness Connector (aa connect)
  • Manual Client Setup Guides
• Developer Workflows
  • Interactive Container Shell
  • Host / Bare-Metal Fallback
  • Quality Gate & CI Verification
• Security & Sandboxing Model
• Contributing
• License & Attribution

Prerequisites

Host requirements for a full development setup:

• Linux (macOS works for development; CI targets Linux)
• Rust (stable), Node.js 20+, Bun 1+, Python 3.11+
• Podman or Docker (for daemon services only)
• git with submodules enabled

Run ./aa setup to check and install missing dependencies automatically.

🏛️ Architecture

System Flow

flowchart TB
    subgraph HostOS["Host Operating System (Linux)"]
        User["User / Developer"]
        Harnesses["AI Agent Harnesses & IDEs\n(Antigravity • Hermes Multi-Profiles • OpenCode • Cursor • Zed)"]
        CLI["Orchestrator CLI: 'aa' / 'agents-arwaky'\n(~/.local/bin/aa)"]
      
        subgraph XDGShared["Shared Host Storage ($HOME Bind-Mount)"]
            Launchers["Host Wrappers: ~/.local/bin/\n(lint-arwaky, codegraph-mcp, context7, etc.)"]
            InternalBin["Container Binaries: ~/.local/share/agents-arwaky/internal-bin/\n(Compiled ELFs, Venv Wrappers, Node Scripts)"]
            XDGConfigs["Configs & Generated MCP:\n~/.config/<tool>/ & mcp_servers.generated.json"]
            XDGSkills["Harness Skills:\n~/.gemini/... • ~/.hermes/skills • ~/.config/opencode/skills"]
        end
    end

    subgraph HostToolchain["Host Native Toolchains"]
        IsolatedRuntimes["Host-Native Toolchains & Libs\nRust/Cargo • Python/uv • Bun/pnpm • C-Libs • Playwright"]

        subgraph AgentsAndTools["Managed Agent & Vendor Engines"]
            InternalAgents["Internal Agents:\nlint-arwaky • vision-arwaky • qwen-web • blender"]
            VendorTools["Vendor Tools & MCPs:\ncodegraph • context7 • ponytail • fetch • 9router"]
        end
    end

    subgraph SidecarServices["Dedicated Background Daemons (Podman)"]
        AnytypeDaemon["Anytype Headless Daemon (Podman Container)\nlocalhost:31012 • Encrypted Local P2P Graph"]
    end

    %% User & CLI interactions
    User --> CLI
    User --> Harnesses
    CLI -- "aa connect (provisions)" --> XDGSkills
    CLI -- "aa mcp generate" --> XDGConfigs
    CLI -- "aa install (builds)" --> IsolatedRuntimes

    %% Host-native execution
    Launchers == "Direct host execution" ==> InternalBin

    %% Harness interactions
    Harnesses -. "Reads config" .-> XDGConfigs
    Harnesses -. "Loads skills" .-> XDGSkills
    Harnesses == "Executes via stdio (JSON-RPC)" ==> Launchers

    %% Host-native execution
    Launchers == "Direct host execution" ==> InternalBin
    InternalBin --> AgentsAndTools
    IsolatedRuntimes -. "Builds & powers runtime" .-> AgentsAndTools

    %% Daemons & Services
    AgentsAndTools -. "anytype-mcp (HTTP :31012)" .-> AnytypeDaemon
    Harnesses -. "AI Requests via 9Router (HTTP Gateway)" .-> VendorTools

Directory Layout

agents-arwaky/
├── agents-arwaky                # Main Orchestration Entrypoint CLI (alias: aa)
├── distrobox.ini.bak            # Archived: container spec (no longer used)
├── mcp_servers.generated.json   # Auto-generated unified MCP client manifest
├── AGENTS.md                    # Operational manual & architecture context for AI agents
├── CONTRIBUTING.md              # Contributor workflows (adding/removing vendor tools)
├── THIRD_PARTY_LICENSES.md      # Upstream licensing compliance records
├── LICENSE                      # Project License (MIT)
│
├── internal/                    # In-House Autonomous Agents & Tools
│   ├── blender-arwaky/          # Headless 3D pipeline & rendering execution engine
│   ├── lint-arwaky/             # Rust-based Architecture Enforcement System (AES)
│   ├── qwen-web-arwaky/         # Playwright-driven browser automation & MCP
│   └── vision-arwaky/           # Computer vision MCP (VLM, OCR, visual memory)
│
├── vendor/                      # Pinned Upstream Repositories (Git Submodules)
│   ├── 9router/                 # Local AI routing gateway & token saver
│   ├── anytype-mcp/             # Anytype desktop & sync integration
│   ├── codegraph/               # Codebase intelligence & graph query engine
│   ├── context7/                # Upstash documentation & context retrieval
│   ├── fetch-mcp/               # Fast, clean web scraping & text extraction
│   ├── google-workspace-mcp/    # Google Workspace integration (Gmail, Drive, Docs, etc.)
│   ├── mnemosyne/               # Universal local AI memory layer & temporal graph
│   └── ponytail/                # Agent architecture patterns & instructions
│
└── tools/                       # Orchestration, CI & XDG Infrastructure
    ├── arwaky/                  # CLI engine implementation & tool manifest
    ├── build/                   # Master cross-compilation pipeline
    ├── ci/                      # Quality gates & syntax validation scripts
    ├── distrobox-archive/        # Archived: old container provisioning scripts
    ├── lib/                     # Shared bash utilities & XDG path helpers
    ├── mcp/                     # Multi-client MCP configuration generator
    └── <vendor-tool>/           # Per-tool installation & wrapper definitions

Quick Start

🚀 Quickstart in 60 Seconds

1. Clone with Submodules

git clone --recurse-submodules https://github.com/rakaarwaky/agents-arwaky.git
cd agents-arwaky

[!TIP] If you previously cloned without submodules, initialize them via:

./aa submodules

2. Verify Host Prerequisites

Ensure Podman (or Docker) is installed for daemon services:

./aa setup

(Runs an automated prerequisite check and optionally installs dependencies using your host package manager: apt, pacman, or dnf).

Required core tools: git, jq, curl, python3. Recommended: cargo (Rust), uv (Python), node/npm/pnpm/bun (Node).

3. Build & Provision (One-Command)

./aa install

This single command executes the end-to-end setup pipeline:

1. Initializes git submodules (vendor/, internal/).
2. Compiles all internal agents and vendor tools natively on host into XDG prefixes.
3. Installs binary launchers to host ~/.local/bin/.
4. Generates unified MCP configurations at mcp_servers.generated.json.

4. Verify System Health

aa doctor
aa status

Available Scripts/Commands

💻 Unified Orchestrator CLI (agents-arwaky / aa)

The repository installs the agents-arwaky CLI and its short alias aa into ~/.local/bin/. It serves as the single pane of glass for monitoring, executing, and managing all ecosystem components.

   ___                           _        
  / _ | _______    _____ _ / /____ __   
 / __ |/ __/ _ \/\/ _ `/  '_/ // /   
/_/ |_/_/  \_/\_/\_,_/_/\_\_, /  
                           /___/   
 agents-arwaky Unified Tool Orchestrator v1.0

Command Reference

[!TIP] You can use agents-arwaky or the short alias aa interchangeably for all commands!

Practical Examples

# Codebase indexing with codegraph
aa run codegraph index .

# Architecture validation across the repository
aa run lint --help

📦 Agent & Tool Catalog

[!TIP] The single source of truth (SSOT) for all tool registrations is tools/config/manifest.json. You can also run aa list or aa mcp list to inspect live tool status from the terminal.

Core In-House Agents (internal/)

Specialized autonomous agents developed specifically for the agents-arwaky ecosystem:

Curated Upstream Vendor Tools (vendor/)

High-performance community tools integrated via Git submodules and sandboxed with isolated XDG prefixes:

🔌 MCP Client Integration

agents-arwaky generates a standardized, unified MCP client configuration file during aa install or aa mcp generate:

📁 File Location: mcp_servers.generated.json

{
  "mcpServers": {
    "context7": { "command": "context7-mcp" },
    "fetch": { "command": "fetch-mcp" },
    "ponytail": { "command": "ponytail-mcp" },
    "anytype": {
      "command": "anytype-mcp",
      "env": {
        "ANYTYPE_API_BASE_URL": "http://127.0.0.1:31012",
        "OPENAPI_MCP_HEADERS": "{\"Authorization\":\"Bearer <YOUR_API_KEY>\", \"Anytype-Version\":\"2025-11-08\"}"
      }
    },
    "codegraph": {
      "command": "codegraph-mcp",
      "args": ["serve", "--mcp"]
    },
    "vision": { "command": "vision-arwaky-mcp" },
    "qwen-web": { "command": "qwen-web-mcp" },
    "blender": { "command": "blender-mcp" },
    "lint": { "command": "lint-arwaky-mcp" }
  }
}

🧠 Anytype Headless Daemon (Podman)

agents-arwaky includes a headless Anytype daemon powered by anytype-cli inside Podman so your AI agents have their own persistent local knowledge graph:

# 1. Start the headless daemon container
aa anytype start

# 2. Check daemon health and API status
aa anytype status

# 3. Generate API key (auto-updates .env and MCP config)
aa anytype auth-key "arwaky-agent-key"

# 4. Invite agent to your Anytype Space (from desktop app invite link)
aa anytype space-join "<your-invite-link>"

# 5. List joined spaces
aa anytype space-list

🔗 Automated Harness Connector (aa connect)

Instead of manually copying configurations, use aa connect to automatically inject all 10 MCP servers and provision 68+ skills into your agent harnesses:

# Connect to specific harness
aa connect --antigravity      # Google Antigravity (~/.gemini/antigravity-cli/mcp_config.json & skills/)
aa connect --hermes           # Hermes Agent (Main profile + auto-detects all multi-profiles)
aa connect --opencode         # OpenCode (~/.config/opencode/opencode.jsonc & skills/)
aa connect --qwencode         # Qwen Code (~/.qwen/settings.json & skills/)

# Connect to all supported harnesses at once
aa connect --all

# Additional Flags:
aa connect --all --force      # Overwrite existing skill files and MCP entries
aa connect --all --dry-run    # Preview changes without modifying files
aa connect --all --mcp-only   # Configure only MCP servers (skip skills)
aa connect --all --skills-only# Provision only skills (skip MCP)
aa connect --all --env-only   # Inject only 9router environment variables
aa connect --clean            # Remove provisioned skills and MCP entries cleanly

[!NOTE] Hermes Multi-Profile Support: aa connect --hermes automatically detects all profiles under ~/.hermes/profiles/<profile>/ (e.g., currie, fangyuan, linus, tesla) alongside the main profile, ensuring all agents share the full tool and skill suite. Environment & Gateway: aa connect also auto-injects NINEROUTER_URL and NINEROUTER_KEY into harness environments (.env) and desktop session configs (~/.config/environment.d/9router.conf).

Manual Client Setup Guides

{
  "mcpServers": {
    "lint": { "command": "lint-arwaky-mcp" },
    "codegraph": { "command": "codegraph-mcp", "args": ["serve", "--mcp"] },
    "context7": { "command": "context7-mcp" },
    "fetch": { "command": "fetch-mcp" },
    "ponytail": { "command": "ponytail-mcp" },
    "vision": { "command": "vision-arwaky-mcp" },
    "qwen-web": { "command": "qwen-web-mcp" },
    "blender": { "command": "blender-mcp" }
  }
}

mcp_servers:
  lint:
    command: lint-arwaky-mcp
  codegraph:
    command: codegraph-mcp
    args: ["serve", "--mcp"]
  context7:
    command: context7-mcp
  fetch:
    command: fetch-mcp
  ponytail:
    command: ponytail-mcp
  vision:
    command: vision-arwaky-mcp
  qwen-web:
    command: qwen-web-mcp
  blender:
    command: blender-mcp

{
  "mcp": {
    "lint": { "type": "local", "command": ["lint-arwaky-mcp"] },
    "codegraph": { "type": "local", "command": ["codegraph-mcp", "serve", "--mcp"] },
    "context7": { "type": "local", "command": ["context7-mcp"] },
    "fetch": { "type": "local", "command": ["fetch-mcp"] },
    "ponytail": { "type": "local", "command": ["ponytail-mcp"] },
    "vision": { "type": "local", "command": ["vision-arwaky-mcp"] },
    "qwen-web": { "type": "local", "command": ["qwen-web-mcp"] },
    "blender": { "type": "local", "command": ["blender-mcp"] }
  }
}

{
  "mcpServers": {
    "lint": { "command": "lint-arwaky-mcp" },
    "codegraph": { "command": "codegraph-mcp", "args": ["serve", "--mcp"] },
    "context7": { "command": "context7-mcp" },
    "fetch": { "command": "fetch-mcp" },
    "ponytail": { "command": "ponytail-mcp" },
    "vision": { "command": "vision-arwaky-mcp" },
    "qwen-web": { "command": "qwen-web-mcp" },
    "blender": { "command": "blender-mcp" },
    "workspace": { "command": "workspace-mcp" },
    "mnemosyne": { "command": "mnemosyne-mcp" }
  }
}

{
  "mcpServers": {
    "lint": { "command": "lint-arwaky-mcp" },
    "codegraph": { "command": "codegraph-mcp", "args": ["serve", "--mcp"] },
    "context7": { "command": "context7-mcp" },
    "fetch": { "command": "fetch-mcp" }
  }
}

{
  "context_servers": {
    "lint": { "command": "lint-arwaky-mcp" },
    "codegraph": { "command": "codegraph-mcp", "args": ["serve", "--mcp"] },
    "context7": { "command": "context7-mcp" },
    "fetch": { "command": "fetch-mcp" }
  }
}

Configuration

Environment variables are read from XDG config paths ($XDG_CONFIG_HOME or ~/.config). Key files: ~/.config/agents-arwaky/env.sh (shell exports) and tool-specific .env files.

🛠️ Developer Workflows & Installation Paradigms

agents-arwaky defines One Installation Paradigm across all tools: local bare-metal build that compiles and installs directly on the host.

1. Local Bare-Metal Mode (Primary & Only)

Compiles runtimes and tools directly on host into native XDG prefixes, exporting binary launchers to ~/.local/bin/. No container indirection for CLI tools.

# Install all tools in ecosystem:
aa install

# Install a specific tool (e.g. fetch, lint, vision, codegraph):
aa install fetch

2. Host Mode (Bare-Metal Fallback)

If running without container permissions (e.g. nested virtualization restrictions), tools can be compiled directly on the host using native runtimes into standard XDG directories:

# Install all tools directly on host:
aa install --host

# Install a specific tool directly on host:
aa install fetch --host

Interactive Container Shell

To inspect the internal toolchains or debug builds inside the sandbox:

aa shell

Quality Gate & CI Verification

To run automated integrity checks (executable permissions, JSON schema validity, submodules state, and ShellCheck):

aa check

See `CONTRIBUTING.md` § Quality Verification & PR Process for details on validation checks and commit conventions.

Clean & Reset Targets

# Remove build artifacts & generated configurations:
aa clean

# Remove exported host binaries (~/.local/bin) and data (~/.local/share):
aa clean --host

# Destroy the sandbox container (preserves your code and host config):
aa destroy

# Deep reset submodules and repository to pristine state:
aa clean --all

🔒 Security & Sandboxing Model

• Local Bare-Metal Execution: Tools compile and run directly on the host OS — no container indirection for CLI tools or MCPs.
• XDG Conformance & Storage Isolation:
  • Compiled binaries reside in ${XDG_DATA_HOME}/<tool>/ (~/.local/share/<tool>/).
  • Host executable wrappers reside in ${XDG_BIN_HOME}/ (~/.local/bin/) as native launchers.
  • Configurations reside in ${XDG_CONFIG_HOME}/<tool>/ (~/.config/<tool>/).
  • Data and reports reside in ${XDG_DATA_HOME}/<tool>/ (~/.local/share/<tool>/).
• Daemon-only Containerization: Only background services (9Router, Anytype) run in Podman rootless containers — they are the only containerized layer. Your host OS /usr and root filesystems remain untouched by toolchain installations.
• Submodule Isolation: Upstream codebases are strictly tracked via Git submodules at pinned commits, preventing unsolicited upstream drift.

[!NOTE] For the complete technical specifications on XDG storage paths, container isolation contracts, and Architecture Enforcement System (AES) rules, see `AGENTS.md` § System Philosophy & Core Invariants.

Testing

Run the full test suite:

./aa test

Individual module tests live under modules/<name>/tests/.

🤝 Contributing

Contributions to internal agents, orchestration wrappers, and documentation are welcome!

• AI Agents & Autonomous Assistants: Please read `AGENTS.md` for operational boundaries, invariants, container execution rules, and directory standards.
• Human Contributors & Developers: Refer to `CONTRIBUTING.md` for detailed step-by-step workflows on:
  • Adding a new vendor tool or MCP server
  • Cleanly removing or deprecating vendor tools
  • Upgrading upstream submodules
  • Contributing to in-house agents under internal/
  • Quality verification gates (aa check)

Quick Pull Request Checklist:

1. Fork the repository & create a feature branch (git checkout -b feat/my-new-tool).
2. Follow the step-by-step workflow in CONTRIBUTING.md.
3. Run verification before committing:

   aa check
   

4. Commit using conventional commits (git commit -m "feat(vendor): add my-new-tool").
5. Open a Pull Request.

License

• Repository & Orchestration Code: Licensed under the MIT License © 2026 rakaarwaky.
• Third-Party Dependencies: Upstream submodules are licensed by their respective original authors under open-source licenses (MIT, Apache 2.0, BSD). Full licensing attributions and copyright notices are maintained in THIRD_PARTY_LICENSES.md.