Tempo

AI-driven code generation CLI. Give Tempo a goal, and it writes, validates, and retries code changes step by step.

Install

npm install -g tempo-agent

Requirements

Tempo uses the Gemini 2.0 Flash model via the Google AI API (free tier available — no billing required).

Set your Gemini API key as an environment variable.

macOS / Linux

export GEMINI_API_KEY=your-key-here

Windows (PowerShell)

# Current session only
$env:GEMINI_API_KEY = "your-key-here"

# Permanently (no need to set it again after restart)
[System.Environment]::SetEnvironmentVariable("GEMINI_API_KEY", "your-key-here", "User")

Get your free API key at aistudio.google.com → Get API Key.

Usage

1. Initialize a project

Run this inside any existing project:

tempo init

Creates a .tempo/ directory with config and folders for Scores, Sessions, and Ideation files.

2. Write an Ideation file

Create a markdown file in .tempo/ideation/my-feature.md:

# Goal
Build a REST API for a todo list

# Context
- Use Express.js
- Use TypeScript
- Store data in memory

# Ideas
- Add pagination
- Add filtering by status

# Final Plan
1. Create Express server entry point
2. Add todo routes (GET, POST, PUT, DELETE)
3. Add in-memory store module

3. Compile it into a Score

tempo compile my-feature.md

Generates .tempo/scores/my-feature.json — a structured execution plan.

4. Edit the Score

Open .tempo/scores/my-feature.json and fill in files_allowed for each Step — the list of files Tempo is permitted to create or modify:

{
  "steps": [
    {
      "id": 1,
      "description": "Create Express server entry point",
      "files_allowed": ["src/index.ts"]
    }
  ]
}

5. Run it

tempo run my-feature

Tempo will:

• Send each Step to the AI with the current file contents
• Write the AI's response back to disk
• Run lint, build, and tests
• Retry up to 3 times on failure, feeding errors back to the AI
• Save a full Session log to .tempo/sessions/

Config

.tempo/config.json controls which commands are used for validation:

{
  "testCommand": "npm test",
  "buildCommand": "npm run build",
  "lintCommand": "npm run lint"
}

Set any value to null to skip that step.

Session History

Every run is saved to .tempo/sessions/session-{timestamp}/:

| File | Contents | |---|---| | step-N.md | Prompt sent, files used, AI response, result | | errors-step-N.md | Validation errors and retry attempts | | diff-N.patch | Git diff after each Step |

Add to your .gitignore:

.tempo/sessions/
.tempo/runs/

How it works

1. Reads the files listed in files_allowed for the current Step
2. Sends them to Gemini with the Step instruction
3. Gemini returns full file replacements
4. Tempo writes them to disk
5. Runs validation — if it fails, sends the errors back to Gemini and retries
6. Moves to the next Step once validation passes