Widgets

A widget is a file ending in .widget.md, in any folder of an Alcoven project. It names a question in a few lines. Alcoven checks every line, draws the answer on the project’s home or inside a document, and shows where each number came from and when. People change it the way they change any file, and every change is a new version.

# Open tasks by person

- Show: bars
- Measure: open tasks
- From: this project
- By: person
- On home: yes

Why it's here: who carries what before the launch.

Ask your AI for one

Ask the AI you work with, in your words:

• “Keep open tasks by person on the project’s home.”
• “What is still waiting for agreement? Keep it on home.”
• “Chart commits to app/ by week for the last six weeks.”
• “Show sign-ups by source for the last 28 days.”

Claude, Claude Code, Codex or another AI app with Alcoven added (how to add it) checks the file with Alcoven before writing it, and writes it when you say yes. In Alcoven, ask the project at the foot of its home: the project’s agent proposes the file, and you put it on record. When you ask about something you’ll want to see again, the AI offers to keep it as a widget.

A widget, line by line

A title, then the lines, then one line on why the widget is there. Only Show and Measure are needed.

When a line can’t be read, Alcoven says which line and what it takes, in the widget, to the AI that checked it, and in its answer to a git push. A push is never turned down for a widget.

Where the numbers come from

A widget reads a source. The project itself and its linked GitHub folders are sources already. Google Analytics, Google Sheets and numbers your product sends are added on the project’s Sources page in Alcoven; a CSV in the project needs only its source file. Each of these is a .source.md file in a folder, naming its measures.

This project

The project’s own record, with nothing to set up: write From: this project, or leave the From line out when no source file has a measure of the same name. Split any measure by person (who a task is for, who a note asks, who is asked to agree or agreed, who made the change) or by folder, the top folder of each item.

Each person sees the counts of what they can open: a task where they see its folder, a note or a part where they see its document. A part’s Got it, Keep and Let go are private, so parts count only by agreement.

A linked GitHub folder

A repository linked to the project offers releases, merged pull requests and commits on its branch, by day, week or month. Merged pull requests are read from the branch’s commits: a merge commit, or a subject ending in (#12). Alcoven reads up to 500 commits for a widget’s days, so keep a busy repository to a few weeks. A list shows the items themselves, and a Mark line puts releases or merges on another widget’s drawing.

Google Analytics

Someone who manages the project adds it on the Sources page with Continue with Google and picks one GA4 property. Alcoven reads its reports and can’t change anything in Google Analytics. Each measure is a name in your words, then a metric, with a filter if it needs one:

- sign-ups: eventCount where eventName is sign_up
- country: by country

The second line is a field a widget can split by. Numbers are fetched again every six hours, and Google says its numbers for the last two days can still change. The source runs on the Google access of the person who added it. If they leave the project, it stops until someone who manages the project puts it on their own access.

Google Sheets

Someone who manages the project picks one spreadsheet in Google’s picker. Alcoven reads only that spreadsheet, and nothing else in their Drive. Google’s screen says Alcoven may change the files they pick; Alcoven only reads them. In the source file, Range says what to read and Days names the column holding each row’s date. Each measure is a column, by its header or its letter:

- orders: column C
- mrr: column mrr, latest
- region: by column region

latest marks a level, such as MRR, which is read as it stands instead of added up. A by column line is a field to split by. Numbers are fetched again every six hours, on the access of the person who picked the sheet.

A CSV or TSV file in the project

Anyone who writes can make one, by hand or with their AI: a source file beside the data, with no access behind it.

# Delivery KPIs

- Service: File in the project
- File: data/kpis.csv
- Days: column date

## Measures

- orders: column orders
- on-time: column on_time, latest
- region: by column region

Everyone who sees both files sees the numbers. The widget reads the CSV as it is now, and its earlier versions stay in the project.

Numbers your product sends

Someone who manages the project makes the source on the Sources page, with the measures it takes, one a line (sign-ups, or mrr: latest for a level). Alcoven shows its key once. Keep it in the product’s secrets, never in its code. A new key stops the old one at once. The product sends each number to the source’s address:

POST https://app.alcoven.co/api/in/<project>/<source id>
Authorization: Bearer <the key>
Content-Type: application/json

{"measure": "sign-ups", "value": 1, "plan": "team"}

• measure is one the source file names. value is a number, 1 if left out.
• at, if given, is when it happened, like 2026-10-14T09:30:00Z: within the last 400 days and at most a day ahead. Now if left out.
• Any other key is a field to split by, like plan: up to five, each name starting with a lower-case letter, then lower-case letters, numbers and _. Text past 80 characters is cut.
• Send up to 100 numbers in one request as a list, or as {"points": [...]}. A request takes up to 64 KB, and a source takes up to 600 requests a minute.
• Alcoven answers 200 with how many it took, 400 with what to fix (and nothing taken), 404 for a wrong address or key, 409 when the project is archived, 413 for a request too large and 429 for too many.
• Days are UTC. A measure is added up by day, or with latest read as its last number of the day. Numbers are kept for 400 days.

The source file holds the address and the measures, so an AI asked to send a number from your product finds what it needs there.

Who sees which numbers

A person sees a widget’s numbers only when they can open both the widget’s folder and its source’s folder, and, for a CSV, the data file too. Otherwise the widget says the numbers aren’t open to them. This project’s counts follow each person’s own view. A source’s key is shown once, to the person who makes the source, and no file holds it. No AI, and nobody else on the project, is given a source’s key or its Google access.

When a number moves

On a line or bars of one added-up measure, such as tasks added, with no split by a field: when the number jumps or drops (by 30% or more, and by at least 3, against the average of the three days or weeks before), the widget asks What happened? and lists what changed on the project around that day, unless a note already sits near that day. Write the reason under it, on that day: it stays in the margin next to the number, for everyone and every AI that reads the widget. Your AI can do the same with Alcoven’s Add a note tool and the day it moved.

Widgets in documents

A line of a document that is only a link to a widget draws the widget there, live:

Orders climbed in the last week, after the new intake form went live.

[Orders per day](orders.widget.md)

Anywhere else, on GitHub, in an editor or in a clone, it stays a link. For a monthly report, start a dated document with the widgets you want and your words around them, then press Write the numbers in: a new version keeps each widget’s numbers as text, as of the day you press it, so the record holds what you told people.

On the project’s home

Widgets with On home: yes are drawn on the project’s home, four at most. Hide takes one off your own home and changes nothing for anyone else. People who get the Monday summary email find the home widgets’ numbers in it.

For AI apps and agents

• Over MCP, Alcoven’s tools Ask a source for numbers (numbers) and Check a widget before writing it (check_widget) run without any AI on Alcoven’s side. check_widget reads a draft the way Alcoven will and names each line it can’t read. Reading a .widget.md gives its numbers, notes by day and where they come from, and opening the project lists the widgets on home.
• In a project’s folder, AGENTS.md describes widgets for Claude Code, Codex and other coding agents. After a git push, Alcoven’s answer reads each widget back, or names the line to fix.
• A widget’s numbers, where they came from and when, are the same for every AI that asks for the same person, so ask for the number with its source instead of computing it again.

If a widget says something is wrong

Help

For anything else, write to info@alcoven.co.