{"id":50263309,"url":"https://github.com/waterduckpani/alfard","last_synced_at":"2026-05-29T15:00:36.435Z","repository":{"id":358091294,"uuid":"1239863068","full_name":"waterduckpani/alfard","owner":"waterduckpani","description":"Local AI agent runtime — secure by default, private by design.","archived":false,"fork":false,"pushed_at":"2026-05-27T10:43:39.000Z","size":862,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-05-27T12:24:13.124Z","etag":null,"topics":["agentic-ai","ai-agents","automation","cli","local-ai","local-ai-agents","open-source","privacy","productivity","python","self-hosted"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/alfard","language":"Python","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/waterduckpani.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":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-15T14:17:27.000Z","updated_at":"2026-05-27T10:43:42.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/waterduckpani/alfard","commit_stats":null,"previous_names":["waterduckpani/alfard"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/waterduckpani/alfard","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/waterduckpani%2Falfard","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/waterduckpani%2Falfard/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/waterduckpani%2Falfard/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/waterduckpani%2Falfard/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/waterduckpani","download_url":"https://codeload.github.com/waterduckpani/alfard/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/waterduckpani%2Falfard/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33657690,"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-05-29T02:00:06.066Z","response_time":107,"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":["agentic-ai","ai-agents","automation","cli","local-ai","local-ai-agents","open-source","privacy","productivity","python","self-hosted"],"created_at":"2026-05-27T12:01:35.143Z","updated_at":"2026-05-29T15:00:36.428Z","avatar_url":"https://github.com/waterduckpani.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cimg width=\"1444\" height=\"506\" alt=\"Alfard banner\" src=\"https://github.com/user-attachments/assets/e5a59f97-2f96-48d6-84ef-4aff7a8c5cea\" /\u003e\n\n\u003cdiv align=\"center\"\u003e\n\n[![PyPI version](https://img.shields.io/pypi/v/alfard?color=black\u0026label=alfard)](https://pypi.org/project/alfard/)\n[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-black)](https://www.python.org/downloads/)\n[![License: MIT](https://img.shields.io/badge/license-MIT-black)](LICENSE)\n[![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-black)]()\n\n**A local AI agent runtime. You own it. You control it. It never acts without you.**\n\n[Quick Start](#quick-start) · [Features](#features) · [Examples](#what-can-you-build-with-it) · [Security](#security) · [Roadmap](#roadmap)\n\n\u003c/div\u003e\n\n---\n\n\u003e 📖 **Full documentation is coming soon.** For now, everything you need is in this README.\n\n---\n\n## What is Alfard?\n\nAlfard runs AI agents on your machine. Each agent has its own persistent memory, connected to your real tools — Gmail, Notion, GitHub, Slack, Linear — and talks to you from your terminal, Telegram, Discord, or Slack simultaneously.\n\nBefore anything irreversible happens, it stops and asks you. That confirmation is logged. Nothing runs silently. Nothing leaves your machine.\n\n---\n\n## What can you build with it?\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e🔍 PR review pipeline\u003c/strong\u003e\u003c/summary\u003e\n\nConnect **GitHub + Slack + Notion**. Set a cron job every hour. When a new pull request lands, your agent reads the diff, reviews the code, and posts a structured audit to Slack — what changed, what looks risky, what questions it has. You reply once to approve. The agent creates a tracked task in Notion automatically.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e📧 Client enquiry intake\u003c/strong\u003e\u003c/summary\u003e\n\nConnect **Gmail + Notion**. When clients send unformatted requests, your agent reads the email, extracts key details, and formats them into a clean entry. Before touching anything, it sends you an approval request in Slack with exactly what it's about to log. One confirmation — it writes the record.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e📋 Daily engineering standup brief\u003c/strong\u003e\u003c/summary\u003e\n\nConnect **GitHub + Linear + Slack**. Schedule at 8am every weekday. It reads all PRs opened in the last 24 hours, checks which Linear tickets moved, and posts a concise brief to your team channel. Your team starts the day with context instead of a catch-up call.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e📝 Release notes from merged PRs\u003c/strong\u003e\u003c/summary\u003e\n\nConnect **GitHub + Notion**. Tell your agent: *\"summarise every PR merged to main since the last tag and draft release notes.\"* It reads the full diff history, groups changes by type — features, fixes, breaking — and drafts a structured Notion page. You review, edit, publish.\n\n\u003c/details\u003e\n\n---\n\n## Quick start\n\n### Step 1 — Install Python 3.11+\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e🍎 macOS\u003c/strong\u003e\u003c/summary\u003e\n\nThe easiest way is [Homebrew](https://brew.sh). If you don't have it, paste this in your terminal first:\n\n```bash\n/bin/bash -c \"$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)\"\n```\n\nThen install Python:\n\n```bash\nbrew install python@3.11\n```\n\nVerify it worked:\n\n```bash\npython3 --version   # should say Python 3.11.x or higher\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e🪟 Windows\u003c/strong\u003e\u003c/summary\u003e\n\n1. Go to [python.org/downloads](https://www.python.org/downloads/) and download the latest Python 3.11+ installer\n2. Run it — **tick \"Add Python to PATH\"** before clicking Install\n3. Open a new Command Prompt and verify:\n\n```cmd\npython --version   # should say Python 3.11.x or higher\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e🐧 Linux\u003c/strong\u003e\u003c/summary\u003e\n\n```bash\nsudo apt update \u0026\u0026 sudo apt install python3.11 python3.11-venv python3-pip -y\n```\n\nFor other distros, use your package manager (`dnf`, `pacman`, etc.) or [pyenv](https://github.com/pyenv/pyenv).\n\nVerify:\n\n```bash\npython3 --version   # should say Python 3.11.x or higher\n```\n\n\u003c/details\u003e\n\n---\n\n### Step 2 — Install pipx\n\n`pipx` installs Python CLI tools in their own isolated environment. It's the cleanest way to install Alfard.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e🍎 macOS\u003c/strong\u003e\u003c/summary\u003e\n\n```bash\nbrew install pipx\npipx ensurepath\n```\n\nThen **close and reopen your terminal** so the path update takes effect.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e🪟 Windows\u003c/strong\u003e\u003c/summary\u003e\n\n```cmd\npip install pipx\npipx ensurepath\n```\n\nThen **close and reopen your terminal**.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e🐧 Linux\u003c/strong\u003e\u003c/summary\u003e\n\n```bash\npip install pipx\npipx ensurepath\n```\n\nThen **close and reopen your terminal**, or run `source ~/.bashrc`.\n\n\u003c/details\u003e\n\n---\n\n### Step 3 — Install Alfard\n\n```bash\npipx install alfard\n```\n\nThat's it. `alfard` is now a global command on your system.\n\n---\n\n### Step 4 — Run setup\n\n```bash\nalfard setup\n```\n\nThis walks you through 6 steps: choosing your LLM provider, adding your API key, connecting integrations, creating your first agent, adding skills, and reviewing everything. Takes about 3 minutes.\n\n\u003e **No LLM API key?** Alfard works with [Ollama](https://ollama.com) — fully local, no account needed. Pick \"Ollama\" during setup.\n\n---\n\n### Step 5 — Open Alfard\n\n```bash\nalfard\n```\n\nThat's it. Navigate everything with arrow keys — your agents, channels, integrations, skills, memory, cron jobs, and settings. No commands to memorise.\n\n\u003cimg src=\"assets/menu.png\" alt=\"Alfard main menu\" width=\"420\" /\u003e\n\nSelect your agent from **my agents**, choose **run**, and Alfard loads its memory, connects all configured channels, and starts listening. Talk to it in the terminal — or from Telegram, Discord, and Slack at the same time. Same agent, same memory, same rules everywhere.\n\n\u003e **Want it running 24/7?** Go to **settings → service** in the menu and install your agent as a background service. It will start on boot, stay alive on all connected channels, and recover automatically if it crashes — no terminal needed, no elevation required.\n\n---\n\n### Power user commands\n\nIf you prefer the terminal directly:\n\n```bash\nalfard run \u003cagent\u003e                # run an agent\nalfard headless \u003cagent\u003e           # channels only — for VPS / homelab\nalfard service install \u003cagent\u003e    # auto-start on boot, crash recovery\nalfard connect \u003cname\u003e             # connect an integration\nalfard channel connect \u003cname\u003e     # connect a channel\nalfard log                        # full audit trail\nalfard cron                       # manage scheduled tasks\nalfard doctor                     # diagnose setup issues\n```\n\n\u003e Full CLI reference → **docs coming soon**\n\n---\n\n## Features\n\n| | Feature | What it does |\n|---|---|---|\n| 🔒 | **Approval gate** | Halts before every irreversible action. You see full details — tool, arguments, source. Type `y` or `n`. Logged either way. Cannot be bypassed. |\n| 🔑 | **Encrypted credentials** | API keys stored as `~/.alfard/.env.enc` — Fernet-encrypted, key lives in your OS keychain. Never in plaintext. |\n| 🧠 | **Typed persistent memory** | 10 categories, valenced, scored by relevance and importance. Persists across every session. |\n| 🔄 | **Reflect cycle** | Every 20 messages, Alfard proposes memory improvements. You approve or reject each one before it takes effect. |\n| 🛡️ | **3-layer injection protection** | Output sanitiser + behavioural gate + strip safety net — web content cannot hijack your agent. |\n| 📋 | **Full audit trail** | Every LLM call, tool execution, gate decision, and session event logged to `audit.jsonl` with UTC timestamps. |\n| 📡 | **Multi-channel** | Terminal, Telegram, Discord, and Slack simultaneously. Approval gate adapts per channel — inline keyboard on Telegram, button embed on Discord. |\n| ⚙️ | **Service mode** | Install your agent as a background service — it runs 24/7 on all connected channels, even when you close your terminal. No elevation required on any platform. `alfard service install/start/stop/status/logs` |\n| ⏱️ | **Cron jobs** | Schedule any agent task on a timer. Full cron UI via `alfard cron`. |\n| 💬 | **Slash commands** | `/new` `/remember` `/status` `/skills` `/reset` `/model` `/help` — in every channel. |\n| 🧩 | **Skills system** | Markdown-defined, per-agent, composable. Comes with 7 built-in. Add your own in `~/.alfard/skills/`. |\n| 🌐 | **Any LLM** | OpenRouter, OpenAI, Anthropic, Ollama, LM Studio. Switch at any time. Your data never has to leave your machine. |\n| 🖥️ | **Interactive menu** | `alfard` opens a full arrow-key menu. Agents, channels, integrations, skills, memory, settings — everything in one place. |\n\n---\n\n## Channels\n\n| Channel | Status | How to connect |\n|---|---|---|\n| Terminal | ✅ Built-in | Always available |\n| Telegram | ✅ Stable | `alfard channel connect telegram` |\n| Discord | ✅ Stable | `alfard channel connect discord` |\n| Slack | ✅ Stable | `alfard channel connect slack` |\n\n---\n\n## Integrations\n\n| Integration | Status | How to connect |\n|---|---|---|\n| Notion | ✅ Stable | `alfard connect notion` |\n| GitHub | ✅ Stable | `alfard connect github` |\n| Linear | ✅ Stable | `alfard connect linear` |\n| Web search (DDG / Brave / SearXNG) | ✅ Stable | Enabled during setup |\n| Gmail | ⚠️ Experimental | `alfard connect gmail` — OAuth via `gogcli`, auto-installed |\n| Google Drive | ⚠️ Experimental | `alfard connect gdrive` — OAuth via `gogcli`, auto-installed |\n\n---\n\n## Supported LLM providers\n\n| Provider | Runs locally | Models |\n|---|---|---|\n| OpenRouter | No | `openrouter/auto` (default) · `google/gemini-3-flash-preview` · `anthropic/claude-sonnet-4-6` · any model on the platform |\n| OpenAI | No | `gpt-4o` (default) · `gpt-4o-mini` · `o4-mini` · custom |\n| Anthropic | No | `claude-sonnet-4-6` (default) · `claude-opus-4-7` · `claude-haiku-4-5-20251001` · custom |\n| Ollama | ✅ Yes | `llama3.2` · `mistral` · `qwen2.5-coder` · any local model |\n| LM Studio | ✅ Yes | Any model loaded in LM Studio |\n\n---\n\n## Memory\n\nEvery agent has a persistent `brain.db` that survives across sessions. Memory is typed into 10 categories:\n\n`fact` · `preference` · `goal` · `project_state` · `procedure` · `mistake` · `tool_pattern` · `decision` · `person` · `constraint`\n\nEach memory has a confidence score, importance weight, and valence. Retrieval blends relevance, recency, and importance — `project_state` always surfaces first.\n\n**Reflect** fires on three triggers — every 20 messages, every 30 minutes idle, every 10 sessions — and proposes improvements based on patterns it finds. You approve or reject each proposal before it writes. Rejected proposals never come back.\n\nAfter every confirmed write, a notification appears in the active channel showing exactly what was remembered and as what type.\n\n\u003cimg src=\"assets/memory-notification.png\" alt=\"Memory notification showing a preference was saved\" width=\"480\" /\u003e\n\n---\n\n## Security\n\nSecurity is the architecture, not a feature layer. Full model in [SECURITY.md](SECURITY.md).\n\n- **Approval gate** — every irreversible action, every channel, cannot be bypassed\n- **Encrypted credentials** — Fernet + OS keychain, automatic plaintext migration on upgrade\n- **3-layer prompt injection protection** — sanitiser + behavioural gate + strip safety net. All sanitised content is source-attributed before it enters LLM context\n- **Sandbox executor** — every tool call runs in an isolated OS subprocess with a hard 30-second timeout. Tools cannot block the runtime\n- **Tool registry + classifier** — every tool is registered as reversible or irreversible at startup. Unregistered tool calls are structurally impossible, not just discouraged\n- **Worktree isolation** — all agent file operations are directed to a disposable git branch, keeping your working tree untouched\n- **Full audit trail** — every event logged, credentials never appear in arguments\n- **Memory secret blocking** — API keys, tokens, passwords blocked before any `brain.db` write\n- **Channel allowlists** — Telegram and Discord require explicit user/guild whitelists\n- **No telemetry** — nothing phones home, ever\n\nTo report a vulnerability, see [SECURITY.md](SECURITY.md#responsible-disclosure). Please do not open a public issue.\n\n---\n\n## Creating an agent\n\nRun `alfard` → **create a new agent**. The soul wizard walks through 5 sections — identity, expertise, communication style, uncertainty behaviour, and optional context about you. Takes about 2 minutes.\n\nOr write `soul.md` directly — it's plain markdown:\n\n```markdown\n# postman\n\n## Purpose\nYou manage email. You read, triage, draft, and send via Gmail.\nYou never send without explicit user approval.\n\n## Personality\nEfficient and direct. Summarise threads in bullet points.\n\n## Rules\n- Always show a draft before calling gmail_send_message.\n- Mark threads read only after the user confirms.\n- Flag anything from investors or customers as high priority.\n```\n\n---\n\n## Architecture\n\nAll user data lives in `~/.alfard/` — nothing is ever written to the Alfard repo or install directory.\n\n```\n~/.alfard/\n├── .env.enc               # API keys — Fernet-encrypted, key in OS keychain\n├── config/\n│   ├── alfard.yaml        # provider, model, approval gate settings\n│   └── integrations.yaml  # connected channels and integrations\n├── agents/\n│   └── \u003cname\u003e/\n│       ├── soul.md        # agent personality and rules\n│       ├── skills.yaml    # active skills for this agent\n│       ├── brain.db       # memory store (SQLite + vectors)\n│       ├── memory/        # embeddings + proposals.jsonl\n│       └── crons.yaml     # scheduled tasks\n├── skills/                # your custom skills\n└── logs/\n    ├── audit.jsonl        # full audit trail — append-only\n    └── cron_jobs.sqlite\n```\n\n---\n\n## Roadmap\n\n- [ ] Local web dashboard — full local UI *(v0.2)*\n- [ ] Agent-to-agent communication\n- [ ] Docker opt-in sandbox for code execution\n- [ ] WhatsApp channel\n- [ ] Bundled Gmail OAuth — no GCP setup required\n\nFollow progress and vote on features → [GitHub Discussions](https://github.com/waterduckpani/alfard/discussions)\n\n---\n\n## Contributing\n\nContributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for dev setup, how to add a channel or integration, running the test suite, and the PR process.\n\nPlease read the [Code of Conduct](CODE_OF_CONDUCT.md) before contributing.\n\n---\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n\n---\n\n\u003cdiv align=\"center\"\u003e\n  Built by \u003ca href=\"https://github.com/waterduckpani\"\u003eBharat Khanna\u003c/a\u003e\n  \u003cbr\u003e\u003cbr\u003e\n  If Alfard is useful to you, a ⭐ on GitHub goes a long way.\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwaterduckpani%2Falfard","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwaterduckpani%2Falfard","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwaterduckpani%2Falfard/lists"}