Convo-Lang

The language of AI

Learn Convo-Lang with Live Demos - https://learn.convo-lang.ai

GitHub - https://github.com/convo-lang/convo-lang

NPM - https://www.npmjs.com/package/@convo-lang/convo-lang

What is Convo-Lang?

Convo-Lang is an open source AI-native programming language and ecosystem for building structured prompts, tool-using agents, and LLM workflows.

It combines:

• a procedural scripting model
• a prompt templating system
• conversation state management
• tool and function calling
• structured output handling
• graph-based agent orchestration

You can run Convo-Lang in JavaScript, TypeScript, Python, from the command line, and directly inside VSCode.

Convo-Lang provides a uniform prompting syntax that is model-agnostic and designed to keep prompts, metadata, control flow, and execution behavior readable in one place.

The language supports advanced capabilities such as function calling, tool usage, structured JSON output, vision, imports, transforms, retrieval flows, and graph-driven execution.

The Convo-Lang ecosystem includes a parser, interpreter, TypeScript/JavaScript/Python libraries, a CLI, and a VSCode extension for syntax highlighting and in-editor execution.

Why Convo-Lang?

Most LLM applications start simple, then become difficult to inspect as prompts, tool wiring, state, routing, and output handling spread across framework code and hidden runtime objects.

Convo-Lang takes a text-first approach. It keeps agent behavior visible and executable in source so you can:

• write prompts and workflow logic in plain text
• keep tools, variables, routing, and transforms close to the conversation
• inspect what the model saw and what the runtime did
• preserve a clear ledger of prompts, tool calls, and results
• target different model providers without rewriting the source language
• build chat flows, agents, and automations with the same core runtime

Index

• Quick Start with NextJS
• Why Convo-Lang?
• Core concepts
• Ecosystem
• VSCode extension
• Model Support
• Using Convo-Lang in JavaScript
• Using the CLI
• CLI configuration
• Learn More
• IYIO ( eye·o )
• Contact
• Change Log

Quick Start with NextJS

You can use npx @convo-lang/convo-lang-cli --create-next-app to quickly start building AI agents powered by Convo-Lang in a NextJS project.

Step 1: Create a project using the Convo CLI

npx @convo-lang/convo-lang-cli --create-next-app

Step 2: Open the newly created project in VSCode or your favorite editor

# Open project directory
cd {NEWLY_CREATED_PROJECT_NAME}

# Open Code Editor
code .
# -or-
vim .
# -or-
# Use GUI

Step 3: Copy the example env file to .env.development

cp example.env.development .env.development

Step 4: Add your OpenAI API key to .env.development

OPENAI_API_KEY={YOUR_OPEN_AI_API_KEY}

Step 5: Start the NextJS server

npm run dev

Step 6: Start modifying example agent prompts in any of the example pages - pages/index.tsx: Routing agent that opens the requested agent - pages/agent/todo-list.tsx: Todo list agent that can manage a todo list - pages/agent/video-dude.tsx: Video player agent that plays the best YouTube videos - pages/agent/weather.tsx: Weather agent that can tell you the weather anywhere in the world

Core concepts

Plain-text authoring

Convo-Lang keeps prompts, tools, variables, and control flow in readable source files instead of hiding behavior in deeply nested config or framework code.

Executable conversations

A Convo script is not just prompt text. It can define variables, functions, imports, triggers, transforms, graph routes, structured outputs, and UI-oriented behaviors.

Transparent execution ledger

Convo-Lang is designed to preserve a clear record of what happened during execution, including prompts, tool calls, results, transforms, routing, and model interactions.

Source-first, provider-targeted

Convo-Lang source acts like a provider-neutral source language that can be flattened and converted into native provider payloads for OpenAI-compatible APIs, AWS Bedrock, OpenRouter, and other integrations.

Ecosystem

Convo-Lang is the core language and runtime of a broader ecosystem.

Convo-Lang Core

Provides the source format, parser, type system, runtime, flattening pipeline, function execution, trigger handling, graph orchestration, imports, transforms, and provider integration.

Convo-CLI

Runs Convo-Lang from the command line and supports local scripting, automation, app scaffolding, model inspection, parsing, conversion, and execution workflows.

Convo-VSCode

Provides syntax highlighting, language tooling, in-editor execution, code block support, and workflows for running and developing .convo and Convo-Make files directly in VSCode.

Convo-REST

A Hono-based REST API for executing Convo-Lang from browser and client applications.

Convo-View

A ReactJS chat UI built around Convo-Lang with support for streaming, file attachments, voice input, live interaction, debugging tools, and extensive customization.

Convo-Make

An LLM-powered scaffolding and generation system inspired by make, built on top of Convo-Lang.

Convo-Db

A hybrid document, graph, and RAG-oriented database designed to work naturally with Convo-Lang.

VSCode extension

You will probably also want to install the VSCode extension for syntax highlighting and other developer niceties. You can install the extension by searching for convo-lang in the VSCode extensions tab.

https://marketplace.visualstudio.com/items?itemName=iyio.convo-lang-tools

After installing the extension, add an OpenAI or AWS Bedrock API key to run prompts directly in the editor.

With the Convo-Lang VSCode extension installed and configured, you can execute Convo scripts directly in VSCode by pressing the play button at the top right of a .convo file or using the (CMD+R) hotkey.

You can also run snippets of Convo scripts embedded in other document types. Just highlight the Convo code you want to run, open the command palette, and search for Complete Convo Conversation, then press enter. The snippet will be opened in a new Convo file and completed. This is great for quick prototyping and testing prompts in your application without having to start the full app.

Model Support

OpenAI

https://platform.openai.com/docs/models

• gpt-5
• gpt-5-mini
• gpt-5-nano
• gpt-4.1
• gpt-4
• gpt-4-turbo
• gpt-4o
• gpt-4o-mini
• o4-mini-deep-research
• o4-mini
• o3
• o3-pro
• o3-mini
• o3-deep-research
• o1-mini
• o1-preview
• gpt-3.5-turbo
• gpt-3.5-turbo-16k

Local LLMs & OpenAI Compatible

Any OpenAI chat completions compatible API can be used with Convo-Lang, including locally hosted LLMs.

• LM Studio - https://lmstudio.ai/docs/app/api/endpoints/openai
• Ollama - https://ollama.com/blog/openai-compatibility
• Llama.cpp - https://github.com/ggml-org/llama.cpp/tree/master/tools/server

OpenRouter

Convo-Lang can be used with OpenRouter's 400+ models - https://openrouter.ai/models - Claude - https://openrouter.ai/models?arch=Claude - Gemini - https://openrouter.ai/models?arch=Gemini - Grok - https://openrouter.ai/models?arch=Grok - DeepSeek - https://openrouter.ai/models?arch=DeepSeek - Mistral - https://openrouter.ai/models?arch=Mistral - Llama2 - https://openrouter.ai/models?arch=Llama2 - Llama3 - https://openrouter.ai/models?arch=Llama3 - Llama4 - https://openrouter.ai/models?arch=Llama4 - OpenAI GPT - https://openrouter.ai/models?arch=GPT - Cohere - https://openrouter.ai/models?arch=Cohere - Nova - https://openrouter.ai/models?arch=Nova - Yi - https://openrouter.ai/models?arch=Yi - RWKV - https://openrouter.ai/models?arch=RWKV - Qwen - https://openrouter.ai/models?arch=Qwen - Qwen3 - https://openrouter.ai/models?arch=Qwen3 - PaLM - https://openrouter.ai/models?arch=PaLM - more - https://openrouter.ai/models

AWS Bedrock

https://aws.amazon.com/bedrock/

• us.amazon.nova-lite-v1:0
• us.amazon.nova-micro-v1:0
• us.amazon.nova-pro-v1:0
• us.anthropic.claude-3-5-haiku-20241022-v1:0
• us.anthropic.claude-3-5-sonnet-20240620-v1:0
• us.anthropic.claude-3-5-sonnet-20241022-v2:0
• us.anthropic.claude-3-7-sonnet-20250219-v1:0
• us.anthropic.claude-3-haiku-20240307-v1:0
• us.anthropic.claude-opus-4-20250514-v1:0
• us.anthropic.claude-sonnet-4-20250514-v1:0
• us.deepseek.r1-v1:0
• us.meta.llama3-1-70b-instruct-v1:0
• us.meta.llama3-1-8b-instruct-v1:0
• us.meta.llama3-2-11b-instruct-v1:0
• us.meta.llama3-2-1b-instruct-v1:0
• us.meta.llama3-2-3b-instruct-v1:0
• us.meta.llama3-2-90b-instruct-v1:0
• us.meta.llama3-3-70b-instruct-v1:0
• us.meta.llama4-maverick-17b-instruct-v1:0
• us.meta.llama4-scout-17b-instruct-v1:0
• us.mistral.pixtral-large-2502-v1:0

Using Convo-Lang in JavaScript

When using Convo-Lang in a TypeScript or JavaScript project, you can use the Convo-Lang conversation engine through the convo template literal or the Conversation class directly.

For many cases, the convo template literal is the fastest way to get started.

Install the package:

npm install @convo-lang/convo-lang

(note - syntax highlighting for Convo-Lang embedded in string template literals is provided by the convo-lang VSCode extension)

// example.mjs
import { convo, initOpenAiBackend } from '@convo-lang/convo-lang';

initOpenAiBackend();

const planets = await convo`
> system
You are a super smart and funny astronomer that loves making funny quotes

> define
Planet = struct(
    name: string
    moonCount: number
    quote: string
)

@json Planet[]
> user
List the planets in our solar system
`;

console.log(planets);

# Set the OPENAI_API_KEY env var however you see fit
export OPENAI_API_KEY=sk-___YOUR_KEY___

node example.mjs

Output:

[
    {
        "name": "Mercury",
        "moonCount": 0,
        "quote": "I'm Mercury. I don't have any moons, but who needs them when you're this close to the Sun? 🍳"
    },
    {
        "name": "Venus",
        "moonCount": 0,
        "quote": "Venus here! No moons in sight, but you should see my cloud cover. It's haute couture! ☁️👗"
    },
    {
        "name": "Earth",
        "moonCount": 1,
        "quote": "Earth, the only planet with pizza! Oh, and one moon which we keep for dramatic lunar eclipses. 🌕🍕"
    },
    {
        "name": "Mars",
        "moonCount": 2,
        "quote": "Mars calling! With my two moons, Phobos and Deimos, I basically have my own double feature in the sky! 🎬🌌"
    },
    {
        "name": "Jupiter",
        "moonCount": 79,
        "quote": "Jupiter, moon hoarder extraordinaire! With 79 moons, my nightly show is never the same—it's cosmic channel surfing! 📺🌔"
    },
    {
        "name": "Saturn",
        "moonCount": 83,
        "quote": "Saturn here, all about those rings AND 83 moons! Talk about accessories stealing the spotlight! 💍🌕"
    },
    {
        "name": "Uranus",
        "moonCount": 27,
        "quote": "Uranus checking in! With 27 moons, I have more natural satellites than most people have friends. 🌑👽"
    },
    {
        "name": "Neptune",
        "moonCount": 14,
        "quote": "Neptune, ruler of the deep space! With 14 moons, I'm never alone, even in the far reaches of the solar system. 🌊🔭"
    }
]

Template literals, functions, and typed output

Convo-Lang can also be embedded directly in JavaScript or TypeScript using the convo template literal.

Host values can be interpolated with standard ${...} syntax, and host functions can be registered as extern functions automatically when passed into the template.

Structured output can also be requested and validated using a Zod schema.

import { convo } from '@convo-lang/convo-lang';
import { z } from 'zod';

const Planet = z.object({
    name: z.string(),
    moons: z.number().int(),
    funFact: z.string(),
});

const planetName = 'Mars';

const planet = await convo`
> system
You are an astronomy assistant

@json ${Planet}
> user
Describe the planet ${planetName}.
`;

console.log('Planet', planet);

For more advanced scenarios such as streaming, event handling, triggers, forks, custom services, or direct runtime control, use the Conversation class directly.

Using the CLI

The Convo CLI can be used to execute Convo scripts from the command line.

For command-line usage, install the @convo-lang/convo-lang-cli package:

npm i -g @convo-lang/convo-lang-cli

# Execute a convo file and print results to stdout
convo talky-time.convo

# Write results to a new file named something.convo
convo talky-time.convo --out something.convo

# Write results back to the source input file for a continuous conversation
convo talky-time.convo --out .

CLI Arguments

| argument | multi | description |