This release is a pre-release and may not be stable for production use.
StarPulse
Declarative state machines for agent work, with an enforced task board and a live view of every task, workflow run and agent session.
Live demo · Documentation · CLI reference · Contributing
StarPulse models each lifecycle in a project (a task board, a delivery pipeline, a skill's steps, a pull request's CI) as a state machine declared in YAML: its states, its transitions, and which writers (the operator, an agent, a named workflow) may make each move. Every move is recorded against its machine in an append-only event store and refused when the machine forbids it, whether it arrives from the CLI, the HTTP API or the web UI. A single page draws every machine live, with tasks, workflow runs and agent sessions moving through it.
Highlights
- Machines as data. Lifecycles, guards and writer permissions are declared in YAML and validated with
starpulse machine validate; a Kanban board is one machine, its states rendered as lanes. - Enforced writes. One write path for the CLI, the API and the page; a forbidden transition is refused, not drawn.
- Event-sourced state. Append-only streams with optimistic concurrency, a transactional outbox and schema upcasters, in a single portable SQLite database.
- Agent-native CLI. Every verb prints JSON with documented exit codes;
starpulse help --agentemits the full verb manifest for an agent's context. - Pluggable sources. Adapters for task trackers, workflow schedulers and agent harnesses, plus a CloudEvents ingest (HTTP and gRPC) for anything else.
- Built-in scheduler. Admission, quiet hours and dispatch of Ready tasks to agent sessions.
- Observable. Prometheus
/metrics, OTLP intake for agent telemetry, and flow and session analytics.
Why StarPulse
Most issue trackers treat a status as a label: anyone, or any agent, can drag a card to any column. StarPulse treats a task's lifecycle as a state machine you declare, and it is built for boards that AI agents work through.
- Moves are enforced, not just drawn. States, transitions and which writers may make each move live in YAML.
[[board.guards]]rules add record-level conditions, for example "Done needs a pull request in references". A forbidden move is refused the same way from the CLI, the HTTP API and the web page, with a reason and the skill that satisfies it.starpulse conformreplays recorded history against the declared machines and prints each violation. - A scheduler that dispatches work to agents. The built-in scheduler admits Ready tasks into agent sessions, with admission limits and quiet hours, so agents pull work from the board instead of waiting to be assigned.
- Paused work says why. A paused task sits in Waiting when it is blocked on something specific, or in Needs attention when a person has to act, with the reason recorded on the task.
- Every change is an event. State lives in append-only, event-sourced streams with optimistic concurrency and a transactional outbox, in one portable SQLite database. Prometheus
/metrics, OTLP agent telemetry and flow and session analytics sit on top of that record. - One model for agents, code and workflows. A task board, a delivery pipeline, a skill's steps and a pull request's CI are all machines. Agents, workflow schedulers such as Dagu or GitHub Actions, and plain code move them through the same enforced write path.
- Yours to run. Install it with
uv tool install starpulseorpipx install starpulseand runstarpulse serve. There is no hosted service and no per-seat pricing;servesupervises its own workers, and your board is files and a database you own.
Compared with a hosted tracker
| Typical hosted tracker | StarPulse | |
|---|---|---|
| Where it runs | The vendor's cloud | Your machine, installed from PyPI |
| Cost | Usually per seat | Free and open source (MIT) |
| Status changes | Free-form; anyone can move anything | Declared machines and guards; refused moves are never written |
| Agent work | Agents act when a person assigns or mentions them | The scheduler admits Ready tasks into agent sessions |
| History | An activity feed | An append-only event log that guards and analytics replay |
Hosted tools such as Linear have polished planning features (cycles, projects, triage) and their own agent platform, where you assign an issue to an agent or @mention it. StarPulse doesn't try to replace that. It is for teams that want the board to enforce the process their agents follow.
Installation
StarPulse requires Python 3.14 or later.
uv tool install starpulse # or: pipx install starpulse
Or run it without installing, with uvx starpulse.
Quick start
starpulse init # scaffold starpulse.toml, board.yaml and .starpulse/board/
export STARPULSE_TOKEN=$(openssl rand -hex 16) # producer token read by the scaffolded config
starpulse serve # open http://localhost:8766
starpulse task create "First task"
init writes a board machine with its roles declared, an example [[board.guards]] rule, a [scheduler] table and
Claude Code telemetry export settings (--harness, --dir to change them). It never overwrites an existing file.
starpulse doctor checks the config, the server and each adapter.
Using StarPulse with agents
Install the bundled skills into a project:
starpulse skills install --claude --codex
For any other harness, point the agent at the CLI from AGENTS.md or CLAUDE.md:
## Tasks
This project tracks work on a StarPulse board. Run `uvx starpulse help --agent` for every verb, its
arguments and exit codes. Read the board with `uvx starpulse board` and open a task with
`uvx starpulse task create "<title>"`.
The same verbs work by hand, and New task on the Kanban view writes to the same board.
Integrations
| Kind | Supported |
|---|---|
| Task trackers | Native Markdown board, Backlog.md, Jira |
| Workflow runs | Dagu, GitHub Actions, systemd timers, any scheduler via CloudEvents |
| Agent sessions | Claude Code (OTLP), GitHub Copilot cloud agent and code review |
New trackers and producers are written against the board, machine-events and runs contracts; see Adapters.
Views
| Kanban | Star Map | Workflow runs |
|---|---|---|
 |
|
 |
Documentation
| Guide | Covers |
|---|---|
| Serve and configure | Server, workers, config file, event store, scheduler, releases |
| Connect sources | Agent telemetry, runs adapters, CloudEvents ingest, pull requests |
| CLI reference | Every verb, its arguments, JSON output and exit codes |
| Write an adapter | Board, machine-events and runs contracts, and the adapter kit |
| Build a consumer | Dashboards, alerts and reports built on the event log export |
| Security | Network exposure, request checks and the trust model |
| Compatibility | The public surface and how releases keep it compatible |
| Development | Building and testing StarPulse from source |
| Development loop | How StarPulse fits a workflow with many concurrent agent sessions |
Status
StarPulse is pre-1.0 and under active development; minor releases may change the config, CLI and API. The public surface lists what is covered by compatibility guarantees. Known gaps:
- Parts of the web UI are incomplete.
- Captured signals are recorded and reported but not yet fed back into scheduling decisions.
Contributing
Bug reports and pull requests are welcome. Open an issue with the command you ran and what you expected, and read CONTRIBUTING.md before sending a change.
License
1 maintainer
Metadata
1 maintainer
Release files for starpulse 0.5.1b2266
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| starpulse-0.5.1b2266.tar.gz | 3.0 MB | Without provenance | Details for starpulse-0.5.1b2266.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| starpulse-0.5.1b2266-py3-none-any.whl | Python 3 | none | any | Details for starpulse-0.5.1b2266-py3-none-any.whl |
Total release size: 6.2 MB
Release files / starpulse-0.5.1b2266.tar.gz
| Download URL | starpulse-0.5.1b2266.tar.gz |
|---|---|
| Size | 3.0 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
9d73fa5fa1a23a8ce39dcec98f345869f45fca653a8c16c2362308b0dc889c7f
|
|
BLAKE2b-256 checksum How to use checksums |
a8964c84bc75bba835a73b263ec67f9a0914e9c9a0727d88afe074f6a2a59ac2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.13.7 {"installer":{"name":"uv","version":"0.13.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / starpulse-0.5.1b2266-py3-none-any.whl
| Download URL | starpulse-0.5.1b2266-py3-none-any.whl |
|---|---|
| Size | 3.2 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
c45fede6fdfb301dc3c1d68b6175bc26966a05f97fc5891c61b9df19ca403c0c
|
|
BLAKE2b-256 checksum How to use checksums |
5eb661646dc10a596d5c95e752de16cadef4a02742573492e031b569ed0b77dd
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.13.7 {"installer":{"name":"uv","version":"0.13.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for starpulse 0.5.1b2266
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
