telos

telos is a goal-oriented programming system.

Install

Via your coding agent

Set up Telos.

- Install it with `curl -fsSL https://usetelos.ai/install.sh | sh`.
- Run `telos login` to sign in to Telos Cloud.
- Read the installed `telos-cli` skill to get started.

Via the CLI

curl -fsSL https://usetelos.ai/install.sh | sh
telos login

The installer supports macOS and Linux on amd64 and arm64.

telos login signs in to Telos Cloud and is required when telos apply targets Cloud.

Get Started

Work with your coding agent to write and iterate on your Goal spec, and have the agent drive telos for you.

The CLI is optimized for the agent experience.

The Goal specification (SPEC.md) is the main entrypoint to a telos program.

A minimal SPEC.md:

---
name: hello-service
version: 0.1.0
platform: cloud
---

# Goal

Run an HTTP service with persistent Postgres storage. Keep `/healthz`
available, preserve stored data across restarts, and return evidence for both.

Skills are modular libraries imported by a spec. Load them from a local path or pin them to an immutable registry version:

skills:
  - path/to/postgres-skill
  - "@scope/service-readiness:1.0.0*"

A trailing * makes a skill a required rubric. Use starred skills for quality, process, or subjective requirements. The revision must pass every starred rubric in an independent evaluation before Ready.

Apply

telos apply reconciles a persistent Goal toward the desired state in SPEC.md.

First, preview the spec without changing the Goal or its target state:

telos plan SPEC.md

After reviewing the plan, apply it:

telos apply SPEC.md

apply returns a session ID when the revision is accepted for work. The work then continues in the background.

After applying, use telos list to find the session and telos describe to check its status:

$ telos list
NAME           STATUS  SESSION
hello-service  ready   sess_123

$ telos describe sess_123
Name      hello-service
Status    ready
Session   sess_123
Revision  sha256:abc123...
Service   https://hello-service.example.com

Common Cloud statuses:

• working — reconciliation is in progress.
• ready — the displayed revision is running and verified.
• needs_attention or failed — check Reason for details.

Follow agent updates with:

telos logs SESSION_ID

To update a live Goal, edit SPEC.md, bump its version, and apply the new revision to the same session:

telos plan SPEC.md --session SESSION_ID
telos apply SPEC.md --session SESSION_ID

telos reconciles the existing live software toward the new desired state.

Read the Telos documentation for the complete workflow.

Local runs

telos run executes a bounded Goal in a local workspace and stops. Use it for one piece of work that does not need the persistent lifecycle of telos apply.

Local runs use the open source pi coding agent:

For a spec with platform: local:

npm install -g @earendil-works/pi-coding-agent
pi # use /login to connect a model provider
telos run SPEC.md --workspace . --until 3
telos describe SESSION_ID
telos logs SESSION_ID

--until 3 stops the run after at most three review cycles.

License

Fair Source (FSL-1.1), converting to Apache-2.0 two years after each release.