teleo

A goal-driven static analysis and code repair tool.

Instead of predicting code forward line-by-line, teleo analyzes programs backward from a target post-condition to find runtime bugs before they execute, then synthesizes minimal diffs to fix them.

Works with JavaScript, TypeScript, and Python.

What it does

Most code assistants try to guess what you want to type next. Linters check for syntax and style issues.

teleo looks at your code as a causal graph:

1. Forecast (teleo forecast): Scans execution paths to detect runtime crashes (TypeError, ReferenceError/NameError, ZeroDivisionError, runaway recursion) before you run your program.
2. Solve (teleo solve --write): Computes the exact backward mutations needed to reach a stable state and applies the diff directly to your file.

You can use it in zero-config mode (analyzes the whole file automatically) or specify explicit target invariants with comments like // @teleo:target status === 200 or # @teleo:target res.ok.

Installation

Run directly with npx:

npx teleo forecast <file>
npx teleo solve <file> --write

Or install globally:

npm install -g teleo

Examples

1. Python (script.py)

Given this file:

def get_user_label():
    return "User: " + 42

get_user_label()

Run forecast:

teleo forecast script.py

Output:

Analyzing causality in: script.py...

CRITICAL Line 2: Illegal binary operand (+) between str and int: '"User: " + 42'
  Prophecy: Executing forward in Python will throw TypeError: can only concatenate str (not "int") to str.

Fix it automatically:

teleo solve script.py --write

Result:

def get_user_label():
    return "User: " + str(42)

get_user_label()

2. JavaScript / TypeScript (handler.js)

Given this file with potential null dereferences and unhandled targets:

// @teleo:target expect(status).toBe(200)
const user = null;
console.log(user.profile.name);

let status = 404;

Run forecast:

teleo forecast handler.js

Output:

CRITICAL Line 2: Dereferencing property 'profile' on 'user' which was explicitly assigned null.
  Prophecy: Executing forward will throw TypeError: Cannot read properties of null (reading 'profile').

CRITICAL Line 4: Causal conflict: 'status' is assigned '404', but target demands '200'.
  Prophecy: Target assertion 'status === 200' is guaranteed to fail because line 4 locked the state to '404'.

Fix it automatically:

teleo solve handler.js --write

Result:

// @teleo:target expect(status).toBe(200)
let user = { profile: { name: "Default" } };
console.log(user?.profile?.name);

let status = 200;

Using with AI CLIs (Claude Code, Cursor, Aider) via MCP

teleo includes a Model Context Protocol (MCP) server so AI coding agents can run causal verification instead of guessing edits.

Add to your MCP configuration (claude_desktop_config.json, Cursor, etc.):

{
  "mcpServers": {
    "teleo": {
      "command": "npx",
      "args": ["-y", "teleo-mcp"]
    }
  }
}

Exposed tools:

• teleo_forecast: Returns structured runtime hazards for a code snippet.
• teleo_solve: Returns the minimal AST mutations to satisfy target invariants.

Packages

This monorepo contains:

• teleo-core: AST program slicing and causal pathfinder engine.
• teleo: CLI interface.
• teleo-mcp: MCP server for AI tools.
• teleo-vscode: VS Code extension wrapper.

Development

# Clone
git clone https://github.com/yanzyuyu/Teleo.git
cd Teleo

# Install & build
npm install
npm run build
npm test

License

Apache-2.0