ProgramOS

A coordinator for your team, and the record it keeps.

ProgramOS is a bot that answers your team's questions by email, from a git repository that is the team's source of truth. It cites the file behind each answer. It writes down decisions, action items and open questions as they happen.

Clone it on GitHub How to start

The code is a close copy of a coordinator that has been tested in production with one program since April 2026. It is open source under the MIT license.

Example exchange (made-up content)

From a team member, by email

Did we decide who signs off on the vendor contract? I need to send it this week.

From the coordinator

Yes. On March 4 the team decided that the operations lead signs contracts under the spending limit, and the director signs above it. discussions/DECISIONS.md

One related question is still open: the spending limit for next year is not set. discussions/OPEN_QUESTIONS.md

  • sender is on the allowlist
  • reply passed the delivery gate
  • exchange written to the audit log

What it does

One place where questions get answered from the record.

It is for a team that runs a project, a program, a grant, a lab or a unit. The knowledge base is a plain git repository of Markdown files that your team owns.

Answers with citations

It searches the repository and replies with the file path behind each statement. It does not invent content.

Records what the team decides

Send it a status update. It extracts decisions, action items and open questions, and commits them.

Sends reminders

Scheduled jobs remind owners of action items and send regular summaries.

Routes approvals

A change that needs a person's approval goes to the person who has that authority, and waits for the answer.

Checks replies before they are sent

A delivery gate on the host inspects each reply. A reply that fails is held, and the operator is told.

Keeps an audit log

Accepted messages and replies are written to a log in your own repository.

How a message moves

The agent works in a container. The host decides what leaves.

  1. Message arrivesEmail, or Telegram for the admin.
  2. Allowlist checkOnly listed senders get an answer. The list is a file in your repository.
  3. Agent in a containerIt sees only the folders you mount. Your credentials stay on the host.
  4. Delivery gateThe host checks the reply and its recipients.
  5. Reply and recordThe reply is sent. The repository and the audit log are updated.

Where the code comes from

What was tested in real use, not a rewrite that nobody has run.

The code is a close copy of K-ai, a coordinator for one online master's program. K-ai has been tested in production with one program since April 2026. It is built on NanoClaw (MIT).

Content removed, code kept

The program's people, addresses, policies and history were removed. The code was not redesigned.

The same tests pass

The 1,761 tests that pass in K-ai pass in this repository. They run on every change.

It stays current

K-ai stays the source. This repository takes its changes through a repeatable export.

Start

Clone it. Your coding agent does the adapting.

You need a host that can run Docker, a mail address for the bot, a git host for the knowledge base, and an AI service that your organization allows your mail to reach. Check that last point first.

  1. Clone the repository. 
    git clone https://github.com/vishalsachdev/programos.git
  2. Open it with your coding agent (Claude Code, Codex, Cursor or another) and say: 
    Read AGENTS.md and help me adapt this for my project.
  3. The agent asks you six questions before it changes anything: which AI service is allowed, who approves, which address the bot uses, where data lives, what senders are told, and which channels you want.
  4. It creates your knowledge-base repository, fills in the settings, and keeps the tests passing.
  5. You review a test exchange. You decide when to deploy.

Safety

Numbered rules, each with the failure it prevents.

The bot works under a set of numbered governance rules. The code, the prompts and the tests cite the rule numbers. Role and access changes are made by the admin only, never because a message asked.

Where the guarantees stop

  • The person allowlist holds for email and Telegram. Web chat checks a shared secret only.
  • Use Telegram with one chat only. With two or more chats, a reply can go to the wrong chat.
  • Sender caps apply to email only, and they reset when the process restarts.
  • Email needs a separate intake service that is not in the repository.

The full list is in SPEC.md, section 11. Read it before you rely on a rule.

Read next

The code is the source of truth. The documents cover what code cannot say.

AGENTS.md
The guide for your coding agent: what to ask, what to replace, safety items, first start.
SPEC.md
The contract: components, channels, modes, knowledge-base layout, audit log.
docs/deployment.md
What kind of host works, and what to start with.
docs/12-governance.md
The numbered rules and how to change one.
templates/program-repo/
A starter knowledge-base repository, in the formats the code reads.