{"id":49037131,"url":"https://github.com/afkbot-io/afkbotio","last_synced_at":"2026-04-19T12:01:44.444Z","repository":{"id":347675975,"uuid":"1194872338","full_name":"afkbot-io/afkbotio","owner":"afkbot-io","description":"Local AI agent runtime and CLI with memory, MCP, browser control, automations, and subagents.","archived":false,"fork":false,"pushed_at":"2026-04-13T08:30:53.000Z","size":2017,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-13T10:26:19.398Z","etag":null,"topics":["ai","ai-agent","automation","browser-automation","chatgpt","claude-code","clawdbot","moltbot","multi-agent","openclaw","subagents"],"latest_commit_sha":null,"homepage":"https://afkbot.io","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/afkbot-io.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":"SECURITY.md","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":"CONTRIBUTOR_LICENSE_AGREEMENT.md"}},"created_at":"2026-03-28T23:22:00.000Z","updated_at":"2026-04-13T08:30:58.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/afkbot-io/afkbotio","commit_stats":null,"previous_names":["afkbot-io/afkbotio"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/afkbot-io/afkbotio","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/afkbot-io%2Fafkbotio","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/afkbot-io%2Fafkbotio/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/afkbot-io%2Fafkbotio/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/afkbot-io%2Fafkbotio/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/afkbot-io","download_url":"https://codeload.github.com/afkbot-io/afkbotio/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/afkbot-io%2Fafkbotio/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32005831,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-18T20:23:30.271Z","status":"online","status_checked_at":"2026-04-19T02:00:07.110Z","response_time":55,"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","ai-agent","automation","browser-automation","chatgpt","claude-code","clawdbot","moltbot","multi-agent","openclaw","subagents"],"created_at":"2026-04-19T12:01:43.673Z","updated_at":"2026-04-19T12:01:44.432Z","avatar_url":"https://github.com/afkbot-io.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AFKBOT\n\nAFKBOT is a source-available local AI runtime and CLI for chat-driven workflows,\ntool calling, automations, and profile-scoped agent environments.\n\nDocumentation lives at [afkbot.io/docs](https://afkbot.io/docs). The project site is [afkbot.io](https://afkbot.io).\nUse the docs site for setup, configuration, MCP, automations, and command reference.\n\n## What AFKBOT does\n\n- Runs local chat sessions with tool access, planning, and configurable reasoning.\n- Supports multiple LLM providers in setup/profile runtime (`openrouter`, `openai`, `claude`, `moonshot`, `deepseek`, `xai`, `qwen`, and `custom`).\n- Provides a CLI-first workflow for setup, chat, health checks, and runtime control.\n- Supports profile-scoped configuration, secrets, permissions, and tool exposure.\n- Includes browser, web, app, MCP, automation, and channel integration surfaces.\n- Exposes a local runtime and API layer for longer-running workflows.\n\n## Runtime Model\n\nAFKBOT uses one session-oriented execution model across chat, API, automations,\nTask Flow workers, and child subagents.\n\n- One active turn runs at a time for each `(profile_id, session_id)`.\n- If you send another message while a turn is still running, the next message is\n  queued and starts after the current turn releases the session slot.\n- `afk chat` planning modes control whether the agent starts with a read-only\n  planning pass before execution:\n  - `off`: execute immediately\n  - `auto`: use plan-first for complex requests\n  - `on`: always show a plan first, then execute\n- A public `plan -\u003e execute` flow runs inside the same serialized session slot,\n  so execution starts automatically after planning unless you explicitly asked\n  for only a plan.\n- Inside one turn, the agent can fan out independent work in parallel with\n  `session.job.run`, wait for every child job to finish, and then return one\n  final answer.\n- Subagents and Task Flow runs use separate child sessions, so they do not steal\n  the parent chat session slot.\n\n## Choosing the Execution Path\n\nUse this mental model:\n\n| Path | Use it when | Wait for the answer now? | Durable state? | Typical outcome |\n| --- | --- | --- | --- | --- |\n| `Chat turn` | The work fits in one bounded conversation turn | Yes | No | Plan, inspect files, run tools, answer in chat |\n| `session.job.run` + subagents | You want parallel work inside the current turn | Yes | No | Fan out independent bash or subagent jobs, wait for all, merge results |\n| `Task Flow` | The work is long-running, needs dependencies, review, handoff, or a backlog trail | Not necessarily | Yes | Create durable tasks, run them in background, inspect task runs and comments later |\n\nCommand examples below use the installed `afk` binary. If you are working from a source checkout without installing AFKBOT into your shell yet, run the same commands with `uv run`, for example `uv run afk doctor`.\n\nSubagents are profile-local runtime assets, not global assistant personas. List\nthe subagents that the current AFKBOT profile can actually run with:\n\n```bash\nafk subagent list --profile default\n```\n\n## Chat And Planning\n\n`afk chat` is the main orchestrator. It decides whether to stay in one turn,\nfan out parallel jobs, or create durable Task Flow work.\n\nPlanning mode examples:\n\n```bash\nafk chat --plan off\nafk chat --plan auto\nafk chat --plan on\n```\n\nBehavior:\n\n- `off`: the turn executes immediately.\n- `auto`: the runtime may do a read-only planning pass for multi-step work.\n- `on`: the runtime always shows a plan first and then executes in the same\n  request.\n- If you explicitly ask only for a plan, AFKBOT returns the plan and stops\n  without starting execution.\n\n## License Model\n\n- AFKBOT source code is available under the `Sustainable Use License 1.0`.\n- Personal use, non-commercial use, and internal business use are allowed.\n- Forking and modifying AFKBOT are allowed, but redistribution must stay free of charge and non-commercial.\n- You may not sell AFKBOT, sell copies of AFKBOT, resell the source code, or offer AFKBOT as a paid hosted or white-label service without separate permission.\n- The repository license does not grant any trademark rights to the AFKBOT name, logo, or branding.\n\n## Requirements\n\n- Python 3.12 or newer for manual source installs\n- `uv` recommended for local development\n- SQLite is the default runtime database for AFKBOT\n- The hosted installers bootstrap `uv`, install AFKBOT as an isolated uv tool, and keep runtime state outside the app source tree\n\n## Install\n\nHosted installer for macOS/Linux:\n\n```bash\ncurl -fsSL https://afkbot.io/install.sh | bash\n# open a new terminal after install\nafk setup\nafk doctor\nafk chat\n```\n\nHosted installer for Windows PowerShell:\n\n```powershell\npowershell -c \"irm https://afkbot.io/install.ps1 | iex\"\n# open a new terminal after install\nafk setup\nafk doctor\nafk chat\n```\n\nLocal installer from a source checkout:\n\n```bash\nbash scripts/install.sh --repo-url \"file://$PWD\"\n# open a new terminal after install\nafk setup\nafk doctor\nafk chat\n```\n\nCommon installer flags:\n\n```bash\n# installer and setup prompts in Russian\ncurl -fsSL https://afkbot.io/install.sh | bash -s -- --lang ru\n\n# install from a specific Git ref\ncurl -fsSL https://afkbot.io/install.sh | bash -s -- --git-ref v1.2.0\n\n# install from a local checkout\nbash scripts/install.sh --repo-url \"file://$PWD\"\n\n# show actions without mutating the machine\nbash scripts/install.sh --dry-run\n\n# skip bootstrap-only setup seeding during install\nbash scripts/install.sh --skip-setup\n```\n\nWhat the installer does:\n\n- bootstraps `uv` into the user-local bin directory if needed\n- installs AFKBOT as an isolated `uv tool`\n- updates shell integration so `afk` is available in new terminals\n- seeds the runtime root with bootstrap-only setup metadata\n- remembers the install source so `afk update` can refresh the same source later\n\nThe installer is idempotent. Rerun it to refresh the installed tool in place, or use `afk update`.\n\n## First Run\n\nFor normal usage, the first-run flow is:\n\n```bash\nafk setup\nafk doctor\nafk chat\n```\n\n- `afk setup` configures the default profile, provider, policy, locale, and runtime defaults\n- `afk setup` also asks whether `afk chat` should check for AFKBOT updates before opening chat\n- `afk doctor` prints the effective runtime/chat ports and checks local readiness\n- `afk chat` is the main entrypoint for real work\n\nSetup and profile policy directly control the tool surface that the runtime can\nuse. In practice:\n\n- enable `Shell` if you want the agent to run shell commands or parallel bash\n  jobs through `session.job.run`\n- enable `Subagents` if you want the agent to run profile-local subagents\n- enable `Task Flow` if you want durable backlog tasks, dependencies, review,\n  and background execution\n- enable `MCP`, `Browser`, `HTTP`, `Apps`, and other capability groups only for\n  the surfaces you actually want exposed to the profile\n\nUseful first-run checks:\n\n```bash\nafk doctor\nafk profile show default\nafk subagent list --profile default\nafk task board --profile default\n```\n\n`afk profile show default` lets you confirm the effective runtime policy and\ncapabilities. `afk subagent list --profile default` shows the actual subagent\nnames that this profile can run.\n\nIf update notices are enabled in setup, interactive `afk chat` checks for a newer AFKBOT build before opening the session and asks:\n\n- `Yes`\n- `No`\n- `Remind in a week`\n\n`No` continues into chat immediately and does not save a permanent skip. `Remind in a week` suppresses all update prompts for seven days. If you disable update notices in setup, chat will not ask at startup.\n\nThe runtime chooses and persists a non-default local port automatically for fresh installs, so use `afk doctor` when you need the actual `runtime_port` or `api_port`.\n\nManual local source setup with `uv`:\n\n```bash\nuv sync --extra dev\nafk setup\nafk doctor\nafk chat\n```\n\nIf the checkout is not installed into your shell PATH, run the same commands with `uv run afk ...` from the repository root.\n\nManual local source setup with `pip`:\n\n```bash\npython3.12 -m venv .venv\nsource .venv/bin/activate\npip install -e .[dev]\nafk setup\nafk doctor\nafk chat\n```\n\n## Local Runtime\n\nAFKBOT uses one local SQLite database by default for runtime state, semantic memory, and chat metadata:\n\n```bash\nexport AFKBOT_DB_URL='sqlite+aiosqlite:///./afkbot.db'\n```\n\nStart the local runtime/API:\n\n```bash\nafk start\nafk doctor\n# doctor prints the effective runtime_port and api_port for this install\n```\n\n`afk start` launches the local runtime stack, including API routes, automation\ndelivery, and Task Flow background workers.\n\nWebhook trigger example:\n\n```bash\ncurl -X POST http://127.0.0.1:\u003cruntime_port\u003e/v1/automations/\u003cprofile_id\u003e/webhook/\u003ctoken\u003e \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"event_id\":\"manual-test-1\"}'\n```\n\nUseful commands:\n\n```bash\nafk version\nafk doctor\nafk setup\nafk chat --message \"Summarize this project\"\nafk automation list --profile default\nafk plugin list\nafk mcp list\nafk profile show default\nafk update\n```\n\n## Chat Examples\n\nPaste prompts like these into `afk chat`.\n\nParallel work inside one turn:\n\n```text\nDo one session.job.run call.\nRun 2 bash jobs in parallel:\n1) sleep 5 \u0026\u0026 echo FIRST\n2) sleep 5 \u0026\u0026 echo SECOND\nWait for both and summarize the result.\n```\n\nParallel profile-local subagents inside one turn:\n\n```text\nDo one session.job.run call.\nRun 2 subagent jobs in parallel:\n1) subagent_name=poet-10-lines, prompt=\"Write 10 lines about orchestration\"\n2) subagent_name=ui-reviewer, prompt=\"Review: button text has low contrast\"\nWait for both and merge the results.\n```\n\nDurable work as Task Flow instead of one large chat turn:\n\n```text\nBreak this project into durable Task Flow work:\n- create a flow\n- create the tasks\n- add dependencies\n- assign AI-owned tasks to the default profile\n- leave me with the task ids and next review points\n```\n\nRule of thumb:\n\n- keep work in one chat turn when you want the answer now\n- use `session.job.run` when the current turn contains independent parallel work\n- use `Task Flow` when the work must survive the current chat session and keep a\n  durable execution trail\n\n## Plugins\n\nAFKBOT supports installable embedded plugins that extend the local platform with:\n\n- API routers\n- static web apps\n- tool factories\n- skill directories\n- app registrars\n- optional startup and shutdown hooks\n\nCurrent curated plugins:\n\n- `afkbotui`: unified AFKBOT web workspace for automations today and future operator surfaces\n\nTypical operator flow:\n\n```bash\nafk plugin list\nafk plugin install\nafk plugin inspect afkbotui\nafk plugin config-get afkbotui\nafk plugin update afkbotui\n```\n\n`afk plugin install` now works as a small wizard:\n\n- it shows curated plugins that are not installed yet\n- today the curated list contains only `afkbotui`\n- the last option is a custom GitHub source, where you can paste a GitHub URL or `github:owner/repo@ref`\n\nYou can still install directly without the wizard:\n\n```bash\nafk plugin install github:afkbot-io/afkbotuiplugin@main\n```\n\nDirect `afk plugin install \u003csource\u003e` also still accepts a local path when you want to install a plugin from a checkout on disk.\n\nThe current curated external plugin is AFKBOT UI. Today it provides the web workspace for automations and is intended to expand into the main operator surface for Task Flow, subagents, MCP, AI settings, and profile management. The older kanban-specific example is no longer the curated plugin path. After installation and `afk start`, it mounts:\n\n- API: `/v1/plugins/afkbotui/...`\n- UI: `/plugins/afkbotui`\n\nPlugin install state lives under the AFKBOT runtime root in `/plugins/...` and is treated as local machine state, not repository content.\n\n## Channels Quickstart\n\nAFKBOT can attach chat transports to a profile for inbound routing and operator workflows.\nUse the docs site for the full command reference; the examples below cover the common setup paths.\n\nTelegram bot polling channel:\n\n```bash\n# guided wizard; omit channel_id to let AFKBOT suggest one\nafk channel telegram add\n\n# fully explicit example\nafk channel telegram add support-bot --profile default --credential-profile support-bot\nafk channel telegram status\nafk channel telegram show support-bot\n```\n\nTelethon user-account channel:\n\n```bash\n# guided wizard; omit channel_id to let AFKBOT suggest one\nafk channel telethon add\n\n# fully explicit example\nafk channel telethon add personal-user --profile default --credential-profile personal-user\nafk channel telethon status --probe\nafk channel telethon show personal-user\n```\n\nNotes:\n\n- Interactive channel setup explains required credentials inline: Telegram bot token comes from `@BotFather`; Telethon `api_id` and `api_hash` come from `my.telegram.org`.\n- If you skip the Telethon session string during setup, finish login later with `afk channel telethon authorize \u003cchannel_id\u003e`.\n- Interactive prompt language follows this order: explicit `--lang` or `--ru`, then the project's saved `prompt_language`, then the current system locale.\n\n## MCP Quickstart\n\nAFKBOT supports profile-local MCP configuration plus runtime MCP tool discovery.\n\nManual CLI flow:\n\n```bash\n# connect one MCP endpoint URL to the default profile\nafk mcp connect https://example.com/mcp --profile default --secret-ref mcp_example_token\n\n# inspect the saved config\nafk mcp get example --profile default\n\n# validate effective MCP files for the profile\nafk mcp validate --profile default\n\n# list all saved MCP servers, including disabled entries\nafk mcp list --profile default --show-disabled\n```\n\nYou can still use the explicit form:\n\n```bash\nafk mcp add --profile default --url https://example.com/mcp --secret-ref mcp_example_token\n```\n\nChat-driven flow:\n\n```text\nConnect this MCP endpoint to my default profile: https://example.com/mcp\nShow me what was saved and validate it.\n```\n\nNotes:\n\n- Use the actual MCP endpoint URL, not a generic product homepage.\n- `afk mcp` and `mcp.profile.*` manage profile config.\n- `mcp.tools.list` and `mcp.tools.call` are the runtime bridge used after a compatible remote MCP server is configured and exposed.\n- If the MCP server needs auth, store only refs in MCP config such as `secret_refs` or `env_refs`; do not hardcode plaintext secrets into MCP JSON.\n\nManaged-install maintenance:\n\n```bash\nafk update\nbash scripts/uninstall.sh --yes\n```\n\n```powershell\nafk update\npowershell -ExecutionPolicy Bypass -File .\\scripts\\uninstall.ps1 -Yes\n```\n\nHosted installers use `uv tool install` under the hood. Advanced equivalents:\n\n```bash\nuv tool install --python 3.12 --reinstall https://github.com/afkbot-io/afkbotio/archive/main.tar.gz\nafk update\nuv tool uninstall afkbotio\n```\n\n## Configuration\n\n- Environment-based configuration examples live in [`.env.example`](https://github.com/afkbot-io/afkbotio/blob/main/.env.example).\n- Setup/provider selection supports OpenRouter, OpenAI, Claude, Moonshot (Kimi), DeepSeek, xAI, Qwen, and custom OpenAI-compatible endpoints.\n- Runtime secrets should be configured through `afk setup`, `afk profile`, or credential commands, not committed into the repository.\n- Manual source setups use a local SQLite database and a local AFKBOT runtime.\n- New installs create the current SQLite schema directly; no legacy migration chain is required.\n- Full setup guidance and user documentation are published at [afkbot.io/docs](https://afkbot.io/docs).\n\n## Development\n\nInstall the development environment and run the standard checks:\n\n```bash\nuv sync --extra dev\nuv run ruff check afkbot tests\nuv run mypy afkbot tests\nuv run pytest -q\n```\n\n## PyPI Release\n\nThe project builds clean Python distributions and passes `twine check`:\n\n```bash\nuv build\nuvx twine check dist/*\n```\n\nFor a safe dry run, upload to TestPyPI first:\n\n```bash\nuvx twine upload --repository testpypi dist/*\n```\n\nThis repository also includes a GitHub Actions publish workflow prepared for trusted publishing:\n\n- `workflow_dispatch`: builds distributions, runs `twine check`, and publishes to `testpypi`\n- `push` on `v*` tags: verifies the tag matches `project.version`, builds distributions, runs `twine check`, attaches them to the GitHub release, and publishes to `pypi`\n\nBefore using the workflow, create matching trusted publishing environments in PyPI:\n\n- `testpypi` for `https://test.pypi.org/p/afkbotio`\n- `pypi` for `https://pypi.org/project/afkbotio/`\n\n## License\n\nAFKBOT is distributed under the `Sustainable Use License 1.0`.\n\n- See [`LICENSE`](https://github.com/afkbot-io/afkbotio/blob/main/LICENSE) for the full license text.\n- See [`LICENSE_FAQ.md`](https://github.com/afkbot-io/afkbotio/blob/main/LICENSE_FAQ.md) for practical allowed/not-allowed examples.\n- See [`COMMERCIAL_LICENSE.md`](https://github.com/afkbot-io/afkbotio/blob/main/COMMERCIAL_LICENSE.md) for commercial-use guidance.\n- See [`TRADEMARKS.md`](https://github.com/afkbot-io/afkbotio/blob/main/TRADEMARKS.md) for brand and name usage rules.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fafkbot-io%2Fafkbotio","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fafkbot-io%2Fafkbotio","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fafkbot-io%2Fafkbotio/lists"}