{"id":50291953,"url":"https://github.com/basedwon/chudbot","last_synced_at":"2026-05-28T06:15:27.019Z","repository":{"id":341817736,"uuid":"1170630089","full_name":"basedwon/chudbot","owner":"basedwon","description":"Chudbot is a stupid-simple “chat in a file” bot.","archived":false,"fork":false,"pushed_at":"2026-03-03T14:21:42.000Z","size":365,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-03-03T15:46:33.622Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","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/basedwon.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"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-03-02T10:40:24.000Z","updated_at":"2026-03-03T12:17:28.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/basedwon/chudbot","commit_stats":null,"previous_names":["basedwon/chudbot"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/basedwon/chudbot","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/basedwon%2Fchudbot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/basedwon%2Fchudbot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/basedwon%2Fchudbot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/basedwon%2Fchudbot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/basedwon","download_url":"https://codeload.github.com/basedwon/chudbot/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/basedwon%2Fchudbot/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33596523,"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-28T02:00:06.440Z","response_time":99,"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":[],"created_at":"2026-05-28T06:15:25.088Z","updated_at":"2026-05-28T06:15:27.004Z","avatar_url":"https://github.com/basedwon.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"chud.png\" width=\"300\" /\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eChudbot\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  Chudbot is a stupid-simple “chat in a file” bot.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/basedwon/chudbot/actions/workflows/ci.yml\"\u003e\n    \u003cimg alt=\"ci\" src=\"https://github.com/basedwon/chudbot/actions/workflows/ci.yml/badge.svg\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/chudbot\"\u003e\n    \u003cimg alt=\"npm\" src=\"https://img.shields.io/npm/v/chudbot\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/chudbot\"\u003e\n    \u003cimg alt=\"downloads\" src=\"https://img.shields.io/npm/dw/chudbot\" /\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\nYou write messages in a `chat.md` file, save it, and Chudbot appends the assistant reply right into the same file.\n\n## What you need\n\n- A computer (Windows or Mac)\n- Node.js (free)\n- An OpenRouter account + API key\n\n## Step 1: Install Node.js\n\n### Windows\n\n1. Go to nodejs.org\n2. Download the LTS installer\n3. Run it (Next, Next, Finish)\n4. Open **PowerShell** (Start menu → type “PowerShell”)\n\n### Mac\n\n1. Go to nodejs.org\n2. Download the LTS installer\n3. Run it\n4. Open **Terminal**\n\nTo confirm Node is installed, run:\n\n```bash\nnode -v\nnpm -v\n```\n\n## Step 2: Install Chudbot\n\nInstall it globally:\n\n```bash\nnpm install -g chudbot\n```\n\nConfirm it works:\n\n```bash\nchudbot --help\n# alias also works\nchud --help\n```\n\n### Optional: check for updates\n\n```bash\nchud update\n```\n\nIf an update is available, Chudbot prints the exact install command. To install automatically, use `-y/--yes` or set `CHUDBOT_AUTO_UPDATE=1`.\n\n## Step 3: Create an OpenRouter account and API key\n\n1. Create an account:\n\n[https://openrouter.ai](https://openrouter.ai/)\n\n1. Create an API key:\n\nhttps://openrouter.ai/settings/keys\n\nYou’ll paste that key into Chudbot’s `.env` in a minute.\n\n## Step 4: Create a folder and open a terminal in it\n\nCreate a new folder anywhere you want, for example:\n\n- `Desktop/chudbot-test`\n\nNow open a terminal and make sure you’re “in” that folder.\n\nIf you already have a terminal open, you can always use `cd` to switch into the folder.\n\n### Windows\n\nOption A (easiest): open PowerShell directly in the folder\n\n1. Open File Explorer and open your `chudbot-test` folder\n2. Click the address bar (where the folder path is)\n3. Type `powershell` and press Enter\n\nOption B: open PowerShell first, then cd\n\n```bash\ncd $HOME\ncd Desktop\ncd chudbot-test\n```\n\n### Mac\n\nOption A: open Terminal, then cd\n\n1. Open Terminal\n2. Type `cd` (with a space)\n3. Drag the folder into the Terminal window\n4. Press Enter\n\nOption B (if enabled): open Terminal at the folder\n\n- In Finder, right-click the folder → Services → New Terminal at Folder\n\n## Step 5: Initialize the folder\n\nThis creates a starter `chat.md` in your folder.\n\nIt also creates `~/.chudbot/.env` if it doesn’t exist yet.\n\n```bash\nchudbot init\n```\n\n## Step 6: Paste your API key into Chudbot’s .env\n\nChudbot reads its API key from your user folder:\n\n- Mac: `~/.chudbot/.env`\n- Windows: `%USERPROFILE%\\\\.chudbot\\\\.env`\n\nOpen that file and set:\n\n```bash\nOPENROUTER_API_KEY=YOUR_KEY_HERE\nOPENROUTER_MODEL=openrouter/free\nOPENROUTER_DEFAULT_MODEL=openrouter/free\n```\n\n`OPENROUTER_MODEL` is the primary env var for model selection.\nIf set, it takes precedence.\n\n`OPENROUTER_DEFAULT_MODEL` is also supported as a fallback when\n`OPENROUTER_MODEL` is not set.\n\n`openrouter/free` routes to a currently-free option on OpenRouter.\nIf it ever errors later, pick a different model.\n\n## Step 7: Use it\n\nOpen `chat.md`, type under the last `# %% user` block, save the file, then run:\n\n```bash\nchudbot run\n```\n\nIt only runs if the chat ends with a non-empty `# %% user` message.\n\nOn success it appends `# %% assistant` with the reply, then appends a fresh `# %% user` header so you can type the next message.\n\n\n### Optional file context injection\n\nYou can inject one or more local files into model context without copy/paste:\n\n```bash\nchudbot run -f src/a.js -f notes/todo.md\nchudbot run -files src/a.js,notes/todo.md\nchudbot run -f src/a.js -files notes/todo.md,README.md\n```\n\nPaths are resolved relative to your current working directory. Files are\nprepended in deterministic order: repeated `-f/--file` entries first (in the\norder provided), then `-files` entries left-to-right.\n\nYou can also set files in `chat.md` front matter:\n\n```markdown\n---\nfiles:\n  - src/a.js\n  - notes/todo.md\n---\n```\n\nThese entries are appended after CLI `-f/--file` and `-files` values.\n\n### Optional trim limits from CLI\n\nYou can cap how much chat history is sent to the model:\n\n```bash\nchudbot run --max-messages 24\nchudbot run --max-tokens 4000\nchudbot run --max-messages 24 --max-tokens 4000\n```\n\nYou can also pass the same limits in watch mode:\n\n```bash\nchudbot watch --max-messages 24 --max-tokens 4000\n```\n\nAnd you can set global defaults once per invocation:\n\n```bash\nchudbot --max-messages 24 --max-tokens 4000 run\nchudbot --max-messages 24 --max-tokens 4000 watch\n```\n\n## Watch mode (auto-reply on save)\n\n```bash\nchudbot watch\n```\n\nStop with **Ctrl+C**.\n\n## How the chat format works\n\nA chat file is just blocks. Each block starts with a header line:\n\n- `# %% system`\n- `# %% user`\n- `# %% assistant`\n\nEverything under that header (until the next header) is the message content.\n\nImportant rule: only type into the LAST `# %% user` block.\n\n## Optional: create memory.md\n\nIf you create a `memory.md`, it gets injected as extra system instructions.\n\nExample `memory.md`:\n\n```markdown\n- My name is Craig\n- Keep answers short and practical\n- I like humor\n```\n\n## Advanced: front matter\n\nAt the very top of `chat.md`, you can add front matter to set the model and memory file for that chat:\n\n```markdown\n---\nmodel: openrouter/free\nmemory: memory.md\n---\n```\n\nIf you want the local memory file to override root memory instead of merging, add:\n\n```markdown\n---\nmemory.override: true\n---\n```\n\nYou can also trim long chats before model calls:\n\n```markdown\n---\nmax_messages: 24\nmax_tokens: 4000\n---\n```\n\nTrimming is deterministic: system messages are kept, the first user message is\nkept as seed continuity, and then the newest remaining messages are kept within\nthe message/token limits.\n\n## Where files are loaded from\n\nChat:\n\n- Uses `chat.md` in your current folder by default (or `--chat`)\n\nEnv:\n\n- Mac: `~/.chudbot/.env`\n- Windows: `%USERPROFILE%\\\\.chudbot\\\\.env`\n\nMemory:\n\n- Root memory: `~/.chudbot/memory.md` (Windows: `%USERPROFILE%\\\\.chudbot\\\\memory.md`)\n- Local memory: `memory.md` next to your `chat.md`\n- Default behavior is merge (root + blank line + local)\n- If `memory.override: true` is set in chat front matter, local memory overrides root\n\n## Troubleshooting\n\n- “Missing OPENROUTER_API_KEY”\n    - Put your key into `~/.chudbot/.env` (Windows: `%USERPROFILE%\\\\.chudbot\\\\.env`)\n- “It didn’t reply”\n    - Make sure the chat ends with a `# %% user` block that has real text\n- “401 / unauthorized”\n    - Your API key is missing or wrong\n- “Model not found”\n    - Try a different `OPENROUTER_MODEL`\n    - Or set `OPENROUTER_DEFAULT_MODEL` if you want a fallback env key\n    - Or set `model:` in chat front matter\n- “It replied twice / weird loop”\n    - Only edit the last `# %% user` block, and let the bot append assistant blocks\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbasedwon%2Fchudbot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbasedwon%2Fchudbot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbasedwon%2Fchudbot/lists"}