{"_id":"@baldaworks/balda","_rev":"5-0b1ba147b79d4365607e2726f0f6d36e","name":"@baldaworks/balda","dist-tags":{"latest":"0.4.2"},"versions":{"0.3.0":{"name":"@baldaworks/balda","version":"0.3.0","keywords":["ai","llm","balda","telegram","agent","cli"],"license":"SEE LICENSE IN LICENSE","_id":"@baldaworks/balda@0.3.0","maintainers":[{"name":"metalagman","email":"alexey.samoylov@gmail.com"}],"bin":{"balda":"balda.js"},"dist":{"shasum":"dc59305c04ad95fe78a5e956e33445f43b419422","tarball":"https://registry.npmjs.org/@baldaworks/balda/-/balda-0.3.0.tgz","fileCount":4,"integrity":"sha512-GW97jLWSS0d+yeZ0ZWAOLyapVUxDwGEJ+MzEONqrxvw4hW7LEc7GfXdke1/SlWxIBA2vhq2b8QwyUriPTqDlkg==","signatures":[{"sig":"MEUCIQC7ckQGL2JzFvgqA1JDzZnxBWJr46kCd1zoboV38midsQIge7T+ssqb/NpoPzGUVjj/FmXG7EwWM+E2bQBeHQKJWGo=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":13683},"engines":{"node":">=16"},"gitHead":"14f128e5ec9d76948c73bb2521b3a3fb7b20fcf5","_npmUser":{"name":"metalagman","email":"alexey.samoylov@gmail.com"},"_npmVersion":"10.9.8","description":"Meta package for balda","directories":{},"_nodeVersion":"22.23.2","_hasShrinkwrap":false,"optionalDependencies":{"@baldaworks/balda-linux-x64":"0.3.0","@baldaworks/balda-win32-x64":"0.3.0","@baldaworks/balda-darwin-x64":"0.3.0","@baldaworks/balda-linux-arm64":"0.3.0","@baldaworks/balda-darwin-arm64":"0.3.0"},"_npmOperationalInternal":{"tmp":"tmp/balda_0.3.0_1787242837461_0.3303081218901618","host":"s3://npm-registry-packages-npm-production"}},"0.3.1":{"name":"@baldaworks/balda","version":"0.3.1","keywords":["ai","llm","balda","telegram","agent","cli"],"license":"SEE LICENSE IN LICENSE","_id":"@baldaworks/balda@0.3.1","maintainers":[{"name":"metalagman","email":"alexey.samoylov@gmail.com"}],"homepage":"https://github.com/baldaworks/balda#readme","bugs":{"url":"https://github.com/baldaworks/balda/issues"},"bin":{"balda":"balda.js"},"dist":{"shasum":"aadd6733968568669ae481c1e9c715b11a7a2140","tarball":"https://registry.npmjs.org/@baldaworks/balda/-/balda-0.3.1.tgz","fileCount":4,"integrity":"sha512-RK8/XFcjlXZB0YDgN0xiTqEo1L7vP6lONPkfJdmZ7n3EegXQ324W1UC0Y8zYe3ZTzLoCR0ke7UOGDSkD2DdLKA==","signatures":[{"sig":"MEYCIQDsRWTb6m9DE7o+OHeRbk9uZui185bmtOZQ4NG38ktXZAIhAO4m4Mvh/scZxYDg7sldLkLm7TZz95uLt0rcsOFoX4h2","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@baldaworks%2fbalda@0.3.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":13862},"engines":{"node":">=16"},"gitHead":"19cc7c5f3176bae853815e35eeb67004753741d9","_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:594e96b8-1303-46e1-813d-7ac87b185b30"}},"repository":{"url":"git+https://github.com/baldaworks/balda.git","type":"git"},"_npmVersion":"11.16.0","description":"Meta package for balda","directories":{},"_nodeVersion":"24.19.0","_hasShrinkwrap":false,"optionalDependencies":{"@baldaworks/balda-linux-x64":"0.3.1","@baldaworks/balda-win32-x64":"0.3.1","@baldaworks/balda-darwin-x64":"0.3.1","@baldaworks/balda-linux-arm64":"0.3.1","@baldaworks/balda-darwin-arm64":"0.3.1"},"_npmOperationalInternal":{"tmp":"tmp/balda_0.3.1_1787245164238_0.3327094281822325","host":"s3://npm-registry-packages-npm-production"}},"0.4.0":{"name":"@baldaworks/balda","version":"0.4.0","keywords":["ai","llm","balda","telegram","agent","cli"],"license":"SEE LICENSE IN LICENSE","_id":"@baldaworks/balda@0.4.0","maintainers":[{"name":"metalagman","email":"alexey.samoylov@gmail.com"}],"homepage":"https://github.com/baldaworks/balda#readme","bugs":{"url":"https://github.com/baldaworks/balda/issues"},"bin":{"balda":"balda.js"},"dist":{"shasum":"a123a97322bab86c6dd44b80227f280544badafe","tarball":"https://registry.npmjs.org/@baldaworks/balda/-/balda-0.4.0.tgz","fileCount":4,"integrity":"sha512-TiuHbxJ0QXydix7SxQFy8LveidNPlUWp4zNcmZJZftdkyku8iqvizMhebGbccjy1NHNS00gRD//Nw3i8HuJ1/w==","signatures":[{"sig":"MEYCIQDxbD8o866/nbocjOSbFqFGHrqqy/AJnvxEGCOtgC71DAIhAK78HozXaqFnKthMclwys3UzKOMhM++dDnnQrPRsQsE0","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEUCIQC5oayS9O39clcywHbZjmb8wuOJ2COyPYTrk9Yk/VjR4QIgWQFR9Kn7GYs6V5suCpwNx6ZIDL0lFoe5Nu5TL8Iy9kg=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@baldaworks%2fbalda@0.4.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":18432},"engines":{"node":">=16"},"gitHead":"bf4a6ae40e69d49f6dc590ae7d52d212824fd351","_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"594e96b8-1303-46e1-813d-7ac87b185b30"}},"repository":{"url":"git+https://github.com/baldaworks/balda.git","type":"git"},"_npmVersion":"11.16.0","description":"Meta package for balda","directories":{},"_nodeVersion":"24.21.0","_hasShrinkwrap":false,"optionalDependencies":{"@baldaworks/balda-linux-x64":"0.4.0","@baldaworks/balda-win32-x64":"0.4.0","@baldaworks/balda-darwin-x64":"0.4.0","@baldaworks/balda-linux-arm64":"0.4.0","@baldaworks/balda-darwin-arm64":"0.4.0"},"_npmOperationalInternal":{"tmp":"tmp/balda_0.4.0_1790663492528_0.9016126489204588","host":"s3://npm-registry-packages-npm-production"}},"0.4.1":{"name":"@baldaworks/balda","version":"0.4.1","keywords":["ai","llm","balda","telegram","agent","cli"],"license":"SEE LICENSE IN LICENSE","_id":"@baldaworks/balda@0.4.1","maintainers":[{"name":"metalagman","email":"alexey.samoylov@gmail.com"}],"homepage":"https://github.com/baldaworks/balda#readme","bugs":{"url":"https://github.com/baldaworks/balda/issues"},"bin":{"balda":"balda.js"},"dist":{"shasum":"6b66e258bb0cc346f9ba10c1d6f9e6f4b4dd89fe","tarball":"https://registry.npmjs.org/@baldaworks/balda/-/balda-0.4.1.tgz","fileCount":4,"integrity":"sha512-aqmfDwusGNGwcHkDqtNISMy6H+RimlkFmjT9UwqmD+Tyh3r1RDLsKbWdyeEzywekYkmEzFDs99+9UiJZBlRP8g==","signatures":[{"sig":"MEQCIDTTjENE9o5wpZFuARjxHgz8lAiCjWhHUBD2zDOcpxX4AiBScQJqBL7uzE25mHp3IT7e1rZeWJjqbzLagEjpHFIlqw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEUCIQDBiBSP0CvBHyQQYiinDlew1D3sdNNw9d6Oz1LZHYNP3QIgQKLe1rKpUu+bSZDrBY0tUZ3ccsn2E3d+DjGU3D4knCU=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@baldaworks%2fbalda@0.4.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":18432},"engines":{"node":">=16"},"gitHead":"ba0fe8f4b6463a67e28d1222f1bc8ab7c06aeaeb","_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"594e96b8-1303-46e1-813d-7ac87b185b30"}},"repository":{"url":"git+https://github.com/baldaworks/balda.git","type":"git"},"_npmVersion":"11.16.0","description":"Meta package for balda","directories":{},"_nodeVersion":"24.21.0","_hasShrinkwrap":false,"optionalDependencies":{"@baldaworks/balda-linux-x64":"0.4.1","@baldaworks/balda-win32-x64":"0.4.1","@baldaworks/balda-darwin-x64":"0.4.1","@baldaworks/balda-linux-arm64":"0.4.1","@baldaworks/balda-darwin-arm64":"0.4.1"},"_npmOperationalInternal":{"tmp":"tmp/balda_0.4.1_1790759576519_0.3343787628149746","host":"s3://npm-registry-packages-npm-production"}},"0.4.2":{"_id":"@baldaworks/balda@0.4.2","bin":{"balda":"balda.js"},"bugs":{"url":"https://github.com/baldaworks/balda/issues"},"dist":{"shasum":"38ef97d90f9fea3f5049870795416f79b734b3dc","tarball":"https://registry.npmjs.org/@baldaworks/balda/-/balda-0.4.2.tgz","fileCount":4,"integrity":"sha512-Ks7BHBYXZDHSiWtpiqR+tryt7qrUFSWZLmggNLqAdW7zPoDAeGPYGOhzuYluCffw0XaT7KavjTRnw3yhi3ATMw==","signatures":[{"sig":"MEQCIC6nYaU4Kl0hxYZ0OI8km7XLWBRUyx+KlduCIbgS5vs9AiAbvThI1rlxpLEoIIZCl7xnCiqiDTKaXpjId/LbN9BwMg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDfIpMjOPeOwhx/mwDHTyeYbNn/o4K1TzXeB31IQifhRQIhAOQYXwrjNSsMMYI+57STAfrIbixJQOn5vigT5mc4mVoI"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@baldaworks%2fbalda@0.4.2","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":18432},"name":"@baldaworks/balda","engines":{"node":">=16"},"gitHead":"86f913988b34131d8c6e1e2fed5eb06b6986a770","license":"SEE LICENSE IN LICENSE","version":"0.4.2","_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"594e96b8-1303-46e1-813d-7ac87b185b30"}},"homepage":"https://github.com/baldaworks/balda#readme","keywords":["ai","llm","balda","telegram","agent","cli"],"repository":{"url":"git+https://github.com/baldaworks/balda.git","type":"git"},"_npmVersion":"11.16.0","description":"Meta package for balda","directories":{},"maintainers":[{"name":"metalagman","email":"alexey.samoylov@gmail.com"}],"_nodeVersion":"24.21.0","_hasShrinkwrap":false,"optionalDependencies":{"@baldaworks/balda-linux-x64":"0.4.2","@baldaworks/balda-win32-x64":"0.4.2","@baldaworks/balda-darwin-x64":"0.4.2","@baldaworks/balda-linux-arm64":"0.4.2","@baldaworks/balda-darwin-arm64":"0.4.2"},"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/balda_0.4.2_1790846664624_0.8069223452404211"}}},"time":{"created":"2026-08-20T16:20:37.353Z","modified":"2026-10-01T09:24:25.030Z","0.3.0":"2026-08-20T16:20:37.608Z","0.3.1":"2026-08-20T16:59:24.367Z","0.4.0":"2026-09-29T06:31:32.601Z","0.4.1":"2026-09-30T09:12:56.611Z","0.4.2":"2026-10-01T09:24:24.729Z"},"bugs":{"url":"https://github.com/baldaworks/balda/issues"},"license":"SEE LICENSE IN LICENSE","homepage":"https://github.com/baldaworks/balda#readme","keywords":["ai","llm","balda","telegram","agent","cli"],"repository":{"url":"git+https://github.com/baldaworks/balda.git","type":"git"},"description":"Meta package for balda","maintainers":[{"name":"metalagman","email":"alexey.samoylov@gmail.com"}],"readme":"# balda\n\n[![test](https://github.com/baldaworks/balda/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/baldaworks/balda/actions/workflows/test.yml)\n[![lint](https://github.com/baldaworks/balda/actions/workflows/lint.yml/badge.svg?branch=main)](https://github.com/baldaworks/balda/actions/workflows/lint.yml)\n\n## Self-hosted engineering agent for team chat\n\nBalda is a self-hosted engineering agent that lives in your team chat and works\ninside your project.\n\nYou can give it a task in chat, open a focused topic for a piece of work, run a\nlonger goal loop, or wire external events into the same workflow. Balda keeps\ncontext, uses your configured tools, and returns something reviewable: a\nsummary, changed files, validation output, a commit, or a concrete next step.\n\n## What Balda is good for\n\n- chat-native engineering help in Telegram, Zulip, Slack Agent, or Mattermost DMs/channel threads\n- focused task threads instead of one shared bot conversation\n- long-running goal execution with progress updates and final results\n- `wedge` style operation: put the agent in the middle of your team workflow so\n  chat, tools, schedules, and external events all feed the same execution path\n- self-hosted deployment close to your repo, config, and credentials\n\n## Quickstart\n\nYou need:\n\n- one chat surface: Telegram, Zulip, Slack, or Mattermost\n- one supported provider CLI installed on the host or in Docker:\n  `codex`, `opencode`, `copilot`, `gemini`, or `claude`\n- Node.js/npm, unless you run the Docker Compose path\n\nInstall:\n\n```bash\nnpm install -g -y @baldaworks/balda\n```\n\nInitialize in your project:\n\n```bash\nbalda init\n```\n\n`balda init` also creates the Backoffice administrator with username `superuser` and prints its generated\npassword once. Save it securely, then start:\n\n```bash\nbalda start\n```\n\n`balda init` creates `.config/balda/config.yaml`, initializes\n`.config/balda/state.db` by default, detects available provider CLIs, and prints\nthe next step for your selected chat provider.\n\nSQLite is the default state database. To select PostgreSQL, configure\n`balda.database.type: postgres`; launch remains `balda start`.\nSee [database configuration and operations](docs/reference/database.md).\n\n`balda start` applies embedded schema migrations to the selected database,\nchecks canonical users and administrator bootstrap, then starts the bot,\nBackoffice, and enabled integrations in one process. Before the first start,\nthe administrator is already bootstrapped on a fresh database. For an existing installation,\nstop Balda, back up the database, and convert legacy owner/collaborator records\nwith an exclusive credentials-output file. See the\n[Backoffice startup and security contract](docs/reference/backoffice.md).\n\n```bash\n# Existing installation with legacy users, while Balda is stopped and after a database backup:\nbalda backoffice migrate-users --credentials-output /run/secrets/balda-migrated-users.txt\nbalda backoffice bootstrap-admin --reset\nbalda start\n```\n\nThe existing-install `--reset` step generates and prints a new password for the\nmigrated primary user. It is needed when that user\nhas a temporary credential; it revokes that user's browser refresh-token\nfamilies. Never pass passwords or generated migration credentials as command\narguments. Distribute the plaintext migration manifest out of band and\nsecurely remove it after verified delivery.\n\n## First run\n\nFor Telegram, authenticate the owner with the command printed by `balda init`:\n\n```text\n/start owner=<owner_token>\n```\n\nThen send a normal direct message to the bot, or open an isolated topic:\n\n```text\n/topic release\n```\n\nFrom there you can:\n\n- ask for ordinary help in chat\n- start a goal loop with `/goalkeeper <objective>`\n- run a session skill with `/skill <skill> [prompt...]` or\n  `/skill <plugin>:<skill> [prompt...]`\n- stop the current turn with `/cancel`\n- reset the current session with `/reset`\n\n## Main workflows\n\n### 1. Ordinary chat work\n\nSend a message in the session where you want work to happen. Balda keeps that\nconversation as the execution context.\n\n### 2. Focused topic work\n\nUse `/topic <name>` to create a separate session for a task, incident, release,\nor stream of work.\n\n### 3. Goal-driven execution\n\nUse `/goalkeeper <objective>` when you want Balda to keep working until there is a\nresult to review.\n\nBalda will:\n\n- work in repeated passes\n- post progress updates\n- ask follow-up questions when critical input is missing\n- return a terminal result with outcome details\n\nSee [docs/goal-workflow.md](docs/goal-workflow.md) for the detailed goal\ncontract.\n\n### 4. Wedge mode\n\nBalda can act as a wedge between team chat and the rest of your engineering\nsystem:\n\n- chat messages start work\n- scheduled jobs wake work up\n- inbound webhooks turn external events into session work\n- the same session can continue through follow-up questions and delayed work\n\nThis is useful when you want one operational path for human requests,\nautomation, and agent execution instead of separate bots and scripts.\n\n## Supported chat providers\n\n- Telegram\n- Zulip\n- Slack Agent DMs and mentioned channel threads\n- Mattermost DMs and mentioned channel threads\n\nBalda maps each conversation scope to its own session:\n\n- Telegram direct chat or personal/group topic\n- Zulip stream + topic\n- Slack Agent DM or mentioned channel thread\n- Mattermost DM, channel, or channel thread\n\nIn Slack channels, every turn requires an explicit `@Balda` mention. A mention\ninside an existing thread can use its preceding accessible discussion and\npersisted files as bounded context; ordinary channel messages never activate\nBalda. With the optional `files:write` scope, generated photos and documents\nare delivered back into the same root thread from bounded local files.\n\n## Docker Compose\n\nBalda ships a root [Dockerfile](Dockerfile) and [compose.yaml](compose.yaml)\nfor local Docker Compose deployment.\n\nThe current directory is mounted as `/workspace`, so Balda sees your checkout,\nconfig, git metadata, and local state.\n\n```bash\ndocker compose build balda\ndocker compose run --rm balda init\ndocker compose up -d balda\n```\n\nPolling mode is the default, so Telegram does not require publishing a port.\nWebhook deployment details live in the\n[configuration reference](docs/reference/configuration.md).\n\n## Published container image\n\nBalda publishes a release image at `ghcr.io/baldaworks/balda:latest`.\n\nThat image contains the `balda` binary only. It does not bundle provider CLIs.\nUse it as a source stage in your own image and add the provider runtime you\nwant.\n\nExample with Codex:\n\n```dockerfile\nFROM node:24-bookworm-slim AS cli-builder\nRUN npm install -g @openai/codex\n\nFROM ghcr.io/baldaworks/balda:latest AS balda\n\nFROM node:24-bookworm-slim\nRUN apt-get update \\\n && apt-get install -y --no-install-recommends \\\n      ca-certificates \\\n      git \\\n      openssh-client \\\n      ripgrep \\\n && rm -rf /var/lib/apt/lists/*\n\nCOPY --from=cli-builder /usr/local/lib/node_modules /usr/local/lib/node_modules\nCOPY --from=cli-builder /usr/local/bin/codex /usr/local/bin/codex\nCOPY --from=balda /usr/local/bin/balda /usr/local/bin/balda\n\nWORKDIR /workspace\nENTRYPOINT [\"balda\"]\n```\n\n## Core commands\n\nBalda provides onboarding, session control, GoalKeeper, locator, usage, skill,\nuser, and plugin commands. Telegram and Zulip use `/skill`, `/locator`, and\n`/reset`; Slack exposes the conversation-scoped forms `/balda skill`,\n`/balda locator`, and `/balda reset`.\n\nSlack formats the response for scanning and copying:\n\n````text\n📍 *Balda Locator* • *Transport:* `slackagent` • *Locator:* `slackagent:c:T0BFTRBFA94:C0BU4LKUB6W`\n\n*Scheduler / webhook configuration*\n```\ntarget: locator\nkey: slackagent:c:T0BFTRBFA94:C0BU4LKUB6W\n```\n````\n\nSee the [complete command reference](docs/commands.md) for syntax, transport\navailability, access, valid contexts, effects, errors, and examples.\n\nOwner plugin lifecycle commands include `install`, explicit origin adoption for\nmigrated installs, `upgrade`, `enable`, `disable`, `rollback`, `remove`,\nexplicit `purge`, and bounded `status`.\nEvery chat command is durably published and executed by `CommandActor`;\nplugin-contributed commands are declarative, revision-pinned normal turns and\nnever native plugin handlers.\n`/skill <skill> [prompt...]` selects one uniquely named skill from the current\nsession snapshot. Use `/skill <plugin>:<skill> [prompt...]` to select an exact\nplugin source. The optional trailing prompt becomes the turn text; the skill\nbody stays lazy until the turn executes. Balda discovers standalone skills from\nthe runtime account's `$HOME/.agents/skills`, `$CODEX_HOME/skills` (defaulting\nto `$HOME/.codex/skills`), `<state_dir>/skills`, and the current workspace's\n`.agents/skills`; enabled plugins contribute their own skills. Run `/reset` to\nadopt skills installed or changed after the session was created.\nSee [Plugins and session capabilities](docs/reference/plugins.md) for the\n`dev.baldaworks.balda` extension schema and the session-bound command, skill,\nand MCP lifecycle.\n\n## Configuration\n\nBalda loads `.config/balda/config.yaml` and then applies `BALDA_*` environment\noverrides. If a local `.env` exists, Balda loads it before resolving config.\n\nMinimal shape:\n\n```yaml\nruntime:\n  providers:\n    codex:\n      type: codex_acp\n      codex_acp: {}\n  mcp_servers: {}\n\nbalda:\n  provider: codex\n  telegram:\n    token: \"\"\n```\n\nCommon settings:\n\n- `balda.provider` — which configured provider runtime to use\n- `balda.telegram.token` — Telegram bot token\n\nExplicit `model` and `reasoning_effort` values on an ACP provider are reapplied\nto restored sessions after restart. Persisted values for settings omitted from\nthe provider configuration remain unchanged, so changing an explicit setting\ndoes not require `/reset`. Custom ACP servers can set `model_config_id` and\n`reasoning_effort_config_id` when their advertised option IDs differ.\n- `balda.telegram.formatting_mode` — Telegram output mode: `rich_markdown`\n  (default), `rich_html`, or `none` for literal plain text\n- `balda.zulip.*` — Zulip outgoing webhook bot credentials and receiver config\n- `balda.mattermost.*` — Mattermost bot credentials (`enabled`, `server_url`,\n  `token`, `bot_user_id`, `bot_username`) for websocket event ingress\n- `balda.slack.*` — Slack Agent credentials plus `agent.*` HTTP/streaming config\n- `balda.webhooks.*` — optional inbound webhook routes\n- `balda.scheduler.jobs` — recurring scheduled jobs\n- `balda.workspace.*` — workspace/worktree behavior for goal execution\n- `balda.permissions.mode` — agent permission policy: `allow_all`, `ask`, or `deny_all`\n- `balda.permissions.timeout` — maximum wait for an interactive permission decision (default `2m`)\n- `balda.memory.enabled` — enable the global explicit-fact memory store and its\n  bundled MCP tools (default `true`)\n- `balda.mcp_servers` — MCP servers injected into Balda-started sessions\n\n### Explicit fact memory\n\nThe bundled `balda.memory.remember` tool stores explicit facts globally for the\nBalda instance. Each update records a latest-memory timestamp. On a subsequent\nsession turn, Balda compares that timestamp with the turn's memory cursor. When\nthey differ, Balda adds the complete current fact-memory snapshot to that same\nprovider user prompt in a delimited application-memory block. Unchanged, empty,\nor disabled memory adds nothing to the prompt. Global fact memory is expected to\nremain small; it is separate from optional durable session memory.\n\n### Knowl sidecar\n\nRun [Knowl](https://github.com/baldaworks/knowl) separately, then register its\nMCP endpoint through Balda's existing generic configuration:\n\n```yaml\nruntime:\n  mcp_servers:\n    knowl:\n      type: http\n      url: http://127.0.0.1:8080/mcp\n\nbalda:\n  mcp_servers:\n    - knowl\n```\n\nThis exposes `knowl_retrieve`, `knowl_ingest`, and `knowl_operation` to\nBalda-started sessions. Balda does not start Knowl, initialize its workspace,\nown its provider/storage configuration, or automatically ingest conversation\nturns.\n\n`allow_all` preserves historical behavior and should be used only where every\nagent tool call is trusted. Production chat deployments should normally set\n`BALDA_PERMISSIONS_MODE=ask`; unsupported channels, missing requester context,\ncancellation, and timeout fail closed.\n\nSet `BALDA_TELEGRAM_FORMATTING_MODE` to override the Telegram mode. Existing\n`markdownv2` configurations must move to `rich_markdown` (or `none`), and\nexisting `html` configurations must move to `rich_html` (or `none`). Balda does\nnot accept compatibility aliases: an unsupported value fails startup before\ningress begins accepting messages. See the\n[Telegram formatting guide](docs/telegram-formatting.md) for rollout and\nfallback details.\n\nFor complete configuration, examples, and provider-specific details, see the\n[configuration reference](docs/reference/configuration.md).\n\n## Troubleshooting\n\n- `telegram token is required` — run `balda init` or set\n  `BALDA_TELEGRAM_TOKEN`\n- `no supported agent CLI detected` — install or expose one of `codex`,\n  `opencode`, `copilot`, `gemini`, or `claude`\n- `balda.provider is required` — rerun `balda init` or set a configured\n  provider id manually\n- webhook or Slack/Zulip startup issues — verify the matching `balda.*`\n  integration settings in config\n- workspace import/export issues — check `balda.workspace.mode`,\n  `balda.workspace.base_branch`, and the git checkout Balda is running in\n\n## Docs\n\n- Technical reference: [docs/balda.md](docs/balda.md)\n- Onboarding: [docs/reference/onboarding.md](docs/reference/onboarding.md)\n- Configuration: [docs/reference/configuration.md](docs/reference/configuration.md)\n- Topic sessions: [docs/reference/topic-sessions.md](docs/reference/topic-sessions.md)\n- Session memory: [docs/reference/session-memory.md](docs/reference/session-memory.md)\n- Operations: [docs/reference/operations.md](docs/reference/operations.md)\n- Goal workflow: [docs/goal-workflow.md](docs/goal-workflow.md)\n- Architecture map: [docs/architecture/index.md](docs/architecture/index.md)\n- Telegram formatting: [docs/telegram-formatting.md](docs/telegram-formatting.md)\n- Zulip webhook setup: [docs/zulip-webhook.md](docs/zulip-webhook.md)\n- Mattermost setup: [docs/mattermost.md](docs/mattermost.md)\n- Slack setup: [docs/slack.md](docs/slack.md)\n- Contributing: [CONTRIBUTING.md](CONTRIBUTING.md)\n\n## Release\n\n- GitHub Releases: <https://github.com/baldaworks/balda/releases>\n- npm package: <https://www.npmjs.com/package/@baldaworks/balda>\n\nnpm releases are published from Git tags through the Omnidist workflow. The\nworkflow uses npm trusted publishing with GitHub Actions OIDC; it does not use a\nlong-lived npm publish token. Each `@baldaworks/balda*` package trusts the\n`baldaworks/balda` repository and the `omnidist-release.yml` workflow.\n","readmeFilename":"README.md"}