A personal assistant you talk to over Telegram. The agent engine is Pi embedded through its SDK. It lives in one workspace directory, runs tools without asking, remembers things in MEMORY.md, and can schedule reminders, prompts, and watcher scripts.

Setup (Windows or any host with Node 24)

On Windows the quickest path is run.bat, which creates .env on the first run, then installs, builds, and starts the bot on every later run. The step by step guide, including how to get the bot token and your user id, is in SETUP-WINDOWS.md.

Create a bot with @BotFather and copy the token.
Find your numeric Telegram user id (send /start to @userinfobot).
Log in to a model provider once with pi so ~/.pi/agent/auth.json exists, or plan to set PI_MODEL plus a provider API key.
Copy .env.example to .env and fill in TELEGRAM_BOT_TOKEN and TELEGRAM_OWNER_ID. Add OPENAI_API_KEY if you want voice notes transcribed.
npm install, then npm run dev (development) or npm run build && npm start.

The bot messages you 🟢 Online. when it is ready. Only your user id is accepted; everyone else is ignored.

Talking to it

Send text, photos, voice notes, or files. Photos go to the model as images. Voice notes are transcribed with OpenAI and echoed back as 🎤 .... Files are saved to workspace/inbox/ and the agent is told the path.

While the agent works you see one ⚙️ Working… message that updates with tool activity, then the answer. Send another message while it works and it is queued for the current run (you get a 👀 reaction).

It can also send files back. When you ask for a screenshot, a generated file, or a rendered report, the agent uses its send tool to attach the file directly — photos appear inline, other files arrive as documents.

Commands: /status, /new, /stop, /jobs, /cancel <id>, /compact.

Scheduling

Ask in plain language:

"Remind me at 9 tomorrow to call the dentist" (one-off, sent directly)
"Every weekday at 8, summarize what's in my inbox folder" (recurring prompt through the agent)
"Write a script that checks the price on this page every 10 minutes and tell me only if it drops below 50" (watcher script)

Watcher scripts follow one rule: print nothing and exit 0 to stay silent, print a message to trigger delivery, exit non-zero on a real error. Failures are reported once and stay quiet while the same failure repeats.

Jobs live in workspace/.secretary/jobs.json.

Workspace

workspace/
  AGENTS.md    persona and standing instructions (edit freely)
  MEMORY.md    facts the assistant keeps; it edits this itself
  scripts/     scripts for scheduled jobs
  inbox/       files you sent
  .secretary/  runtime state

The agent's edits to MEMORY.md are local runtime data. Leave them uncommitted, or run git update-index --assume-unchanged workspace/MEMORY.md.

Environment variables

Variable	Required	Default	Purpose
`TELEGRAM_BOT_TOKEN`	yes		Bot token
`TELEGRAM_OWNER_ID`	yes		Your numeric user id
`WORKSPACE_DIR`	no	`./workspace`	Workspace directory
`OPENAI_API_KEY`	no		Enables voice transcription
`STT_MODEL`	no	`gpt-4o-transcribe`	OpenAI transcription model
`PI_MODEL`	no	first model with credentials	`provider/model` or `provider/model:thinking`, for example `pi-claude-code-provider/opus` with the Claude Code subscription package; `pi --list-models` shows every id
`PI_CODING_AGENT_DIR`	no	`~/.pi/agent`	Pi config directory (auth, settings, packages)
`SECRETARY_TIMEZONE`	no	system	IANA timezone for cron and time display
`SECRETARY_SHELL`	no	Git Bash / bash	Shell used for scheduled scripts
`LOG_LEVEL`	no	`info`	`debug`, `info`, `warn`, `error`
`PLAYWRIGHT_ENABLED`	no	`false`	Enable the Playwright MCP bridge (browser control tools)
`PLAYWRIGHT_HEADLESS`	no	`true`	Run browser headless. `false` opens a visible window
`PLAYWRIGHT_BROWSER`	no	`chrome`	`chrome`, `firefox`, `webkit`, or `msedge`
`PLAYWRIGHT_EXTRA_ARGS`	no		Extra flags passed to `@playwright/mcp` (shell-quoted)

Keeping it running on Windows

Use Task Scheduler (run node dist/main.js at logon, restart on failure) or npm i -g pm2 then pm2 start dist/main.js --name secretary. If Git is installed per-user or somewhere else entirely, set SECRETARY_SHELL to the full path of bash.exe.

Docker / Coolify

docker compose up -d --build runs it with two named volumes: /workspace and /pi-agent. Provide the environment through Coolify. For model auth either copy a Pi agent directory containing auth.json into the /pi-agent volume, or set ANTHROPIC_API_KEY and PI_MODEL=anthropic/claude-opus-4-7 (an id from Pi's built-in Anthropic provider, which is what an API key unlocks). The image includes bash, git, ripgrep, and Python 3 so watcher scripts work the same as on Windows.

Tests

npm test runs the unit tests. SECRETARY_SMOKE=1 npx vitest run src/agent/pi-backend.smoke.test.ts runs one real model call through Pi.

Manual end-to-end checklist

Run npm run dev with a real bot and walk through every line:

hi → progress message appears then disappears, reply arrives as formatted text.
Long answer (explain git rebase in detail with code examples) → multiple messages, code blocks render, no HTML shows raw.
Photo with caption what is this → reply describes the image.
Voice note → 🎤 <transcript> then a reply. Without OPENAI_API_KEY → the not-configured note.
Document (a small .csv) with caption summarize this → file appears in workspace/inbox/ with date prefix, reply uses it.
Send a message while a long run is in progress → 👀 reaction, and the agent picks it up in the same run.
/stop during a run → Stopped. and no final answer message.
remind me in 2 minutes to stretch → confirmation with the fire time; two minutes later <job name>: <message> arrives directly.
every minute run scripts/ping.py and tell me if it prints something where ping.py prints on even minutes → messages arrive only on even minutes; /jobs lists it; /cancel <id> removes it.
Ask it to remember a fact (remember that my dog is called Rex), then /new, then what is my dog called → answer comes from MEMORY.md.
Stop the daemon, start it again → conversation continues (what did we just talk about).
/compact → reply with token counts.
"Every Monday and Wednesday at 9 create a standup event for 15 minutes" → an event is created with RRULE:FREQ=WEEKLY;BYDAY=MO,WE; "list the next 3 standups" returns three occurrences; "move next Wednesday's standup to 10" changes just that instance; "delete the standup series" removes them all.
Start with PLAYWRIGHT_ENABLED=true. Startup log shows playwright tools enabled (N tools) with N > 20. Ask "open https://example.com and tell me the H1 text" → reply contains Example Domain.
With Playwright still enabled, ask "screenshot https://example.com and send it to me" → an image attachment arrives.
Ask "run this on example.com: async (page) => { await page.goto('https://example.com'); return await page.title(); }" → reply says Example Domain. Exercises browser_run_code_unsafe.
Restart with PLAYWRIGHT_ENABLED=false. Startup log shows playwright tools disabled; no browser_* tools appear in the model's tool list.
Ask "write a short poem to poem.txt and send it to me" → a .txt document attachment arrives with the poem inside, and the reply confirms with one line.