GitHub - nahuelsoria/afk-agents: Scaffold and manage unattended AFK agents: cron + bash + Telegram + the Claude CLI. Zero dependencies. · GitHub
/" data-turbo-transient="true" />
Skip to content
Type / to search
Sign in<br>Sign upAppearance settings
You signed in with another tab or window. Reload to refresh your session.<br>You signed out in another tab or window. Reload to refresh your session.<br>You switched accounts on another tab or window. Reload to refresh your session.
Dismiss alert
{{ message }}
nahuelsoria
afk-agents
Public
Notifications<br>You must be signed in to change notification settings
Fork
Star
main
BranchesTags
Go to file
CodeOpen more actions menu
Folders and files<br>NameNameLast commit message<br>Last commit date<br>Latest commit
History<br>2 Commits<br>2 Commits
bin
bin
templates
templates
test
test
.gitignore
.gitignore
LICENSE
LICENSE
README.md
README.md
package.json
package.json
View all files
Repository files navigation
afk
Scaffold and manage unattended AFK agents from the command line: uptime monitors, LLM error triage, weekly digests. All cron + bash + Telegram + the Claude CLI. Zero dependencies, and the agents it generates are plain bash with no runtime dependencies of their own.
This is the authoring tool for the AFK Agents Kit patterns: instead of copying a template folder and wiring cron by hand, you run one command.
Install
npm install -g afk-agents
Requires Node 18+ (to run the CLI) and, on the target box, bash, cron and curl. The Claude CLI is optional and only needed for the worker and digest agent types.
Quickstart
afk init # set up ~/agents with shared helpers + env.sh<br># edit ~/agents/shared/env.sh: add your Telegram token and chat id<br>afk new monitor disk-watch --every 30m # an alert-only check, every 30 minutes<br>afk new digest weekly --day sun --at 19:00 # a weekly LLM digest, Sundays at 19:00<br>afk list # see everything and when it runs
$ afk new monitor disk-watch --every 30m<br>afk: created monitor "disk-watch"<br>/home/you/agents/disk-watch/run.sh<br>scheduled: */30 * * * *<br>edit the CHECK block, then 'afk run disk-watch' to test
$ afk list<br>disk-watch */30 * * * * [08:00:12] ok (41%)<br>weekly 0 19 * * 0 (no runs yet)
Commands
Command<br>What it does
afk init<br>Create AGENTS_HOME with the shared notifier, logger and env.sh (never overwrites an existing env.sh)
afk new [schedule]<br>Create an agent. Types: monitor, worker, digest
afk list<br>Show every agent, its cron schedule and its last log line
afk run<br>Run an agent once, right now (for testing)
afk logs<br>Print today's log for an agent
afk rm<br>Delete an agent's files and its cron line
Scheduling flags for new
Flag<br>Result
--every 30m<br>*/30 * * * *
--every 2h<br>0 */2 * * *
--at 09:00<br>0 9 * * * (daily)
--day sun --at 19:00<br>0 19 * * 0 (weekly)
--schedule "0 2 * * *"<br>used verbatim (raw 5-field cron)
Omit them and the agent is created but not scheduled; add a schedule later by editing your crontab, or re-create it.
The three agent types
monitor : an alert-only check. Silence means OK; it messages you only when something is wrong, and it dedups so a persistent failure does not page you every run.
worker : a queue worker that runs Claude headless with hard guardrails (read-only tools, a daily spend cap, a lock, a timeout). Drop .job files in its queue/ dir.
digest : a scheduled LLM summary that archives everything it generates to disk before sending it.
How it works
Agents live in AGENTS_HOME (default ~/agents), one folder each, sharing the helpers in shared/.
Scheduling edits your user crontab, tagging each line with # afk: so afk can find, replace and remove it without touching your other cron jobs.
Nothing runs as a daemon. Cron is the scheduler, Telegram is the surface.
Configuration
AGENTS_HOME: where agents live (default ~/agents).
AFK_CRONTAB_CMD: the crontab binary to use (default crontab); handy for testing.
License
MIT
About<br>Scaffold and manage unattended AFK agents: cron + bash + Telegram + the Claude CLI. Zero dependencies.<br>Resources<br>Readme<br>MIT license<br>Activity<br>Stars<br>0 stars<br>Watchers<br>0 watching<br>Forks<br>0 forks<br>Report repository
Releases
Packages
Contributors
Languages
You can’t perform that action at this time.