Orchid is a lightweight, composable language for describing how AI agents should think - not just what they should compute. It bridges the gap between natural language prompts and procedural code, giving you human-readable scripts that are machine-executable.

@orchid 0.1
@name "Quick Research Brief"

sources := fork:
    academic: Search("quantum computing breakthroughs 2024")
    industry: Search("quantum computing commercial applications")

vetted := CoVe(sources)                            # verify claims against evidence
analysis := CoT(vetted)<deep>                      # chain-of-thought reasoning

if Confidence(analysis) > 0.7:
    Formal(analysis)<cite>                         # high confidence → rigorous report
else:
    ELI5(analysis) + Explain("uncertainty areas")  # low confidence → be transparent

Read it aloud. You don't need to be a programmer to understand what this agent will do.

Getting Started

Install from npm

npm install -g @orchid-dsl/orchid
orchid examples/hello_world.orch

From source

git clone https://github.com/orchid-dsl/orchid.git
cd orchid && npm install && npm run build
node dist/cli.js examples/hello_world.orch

See the Quickstart guide for MCP setup and more.

Why Orchid?

The problem: We're orchestrating increasingly sophisticated AI agents using either raw prompts (fragile, non-composable) or general-purpose programming languages (verbose, obscures intent). A product manager can't review a LangChain pipeline. A researcher can't reproduce a prompt chain from a Python script.

The approach: Orchid treats reasoning as a first-class primitive. Instead of writing code about API calls, you write scripts about cognition - with named reasoning strategies, confidence-aware control flow, and parallel execution built into the syntax.

| Feature | Orchid | Python + LangChain | YAML Configs | DSPy | |---|---|---|---|---| | Human-readable | ✓ | ✗ | ~ | ✗ | | Reasoning as primitives | ✓ | ✗ | ✗ | ~ | | Native confidence handling | ✓ | ✗ | ✗ | ✗ | | Composable agents | ✓ | ~ | ✗ | ~ | | Parallel execution | ✓ | ~ | ✗ | ✗ | | No programming required | ✓ | ✗ | ~ | ✗ | | Tool integration (MCP) | ✓ | ~ | ~ | ✗ | | Formal grammar | ✓ | N/A | ✓ | ✗ |

Key Concepts

Reasoning Macros

Named cognitive operations that shape how an agent thinks. Not functions that transform data - patterns of thought.

CoT("analyze market trends")          # chain-of-thought deliberation
CoVe(claims)                          # chain-of-verification fact-checking
RedTeam(plan)                         # adversarial analysis
ELI5(report)                          # simplify for general audience
Debate("should we expand to EU?", count=3)  # 3-perspective argumentation

Confidence-Aware Control Flow

Agent operations don't just succeed or fail - they exist on a spectrum. Orchid makes uncertainty a native concept.

while Confidence() < 0.7:
    Search("additional evidence")<append>
    Refine(analysis)

Parallel Execution

Fork operations run concurrently and collect results.

data := fork:
    market: Search("EV market data")
    tech: Search("battery R&D breakthroughs")
    policy: Search("EV policy incentives")

report := Consensus(data)

Tags (Behavior Modifiers)

Fine-grained control over how operations execute, without changing what they do.

Search("topic")<deep, retry=3, timeout=30s>
CoT("sensitive analysis")<private, verbose>
Validate(output, criteria="complete")<retry=5, fallback=draft>

MCP Tool Integration

First-class integration with the Model Context Protocol for external tool access. Use real MCP servers for filesystem, databases, web search, GitHub, and more.

@requires MCP("filesystem")

tree := filesystem:directory_tree(path="src")
pkg := filesystem:read_text_file(path="package.json")
analysis := CoT("describe this project:\n$tree\n$pkg")
filesystem:write_file(path="/tmp/summary.md", content=analysis)

Install servers with one command:

node dist/cli.js mcp install filesystem brave-search memory github

Examples

| Example | MCP Servers | Description | |---|---|---| | hello_world.orch | none | Minimal: search, verify, reason, present | | deep_research.orch | none | Research agent with fork loops, self-critique, iterative refinement | | fs_test.orch | filesystem | Read project files, analyze codebase, write summary | | threat_model.orch | filesystem | STRIDE threat modeling from actual source code | | financial_analysis.orch | brave-search, filesystem | Live news search, multi-angle stock analysis, adversarial review | | adaptive_tutor.orch | memory | Assess understanding, build lesson plan, persist to knowledge graph | | code_review.orch | github | Fetch PR, multi-angle review (correctness, security, design, testing) |

Project Structure

orchid/
├── src/
│   ├── cli.ts                     # CLI entry point
│   ├── index.ts                   # Library exports
│   ├── lexer/                     # Tokenizer
│   ├── parser/                    # Recursive descent parser → AST
│   └── runtime/
│       ├── interpreter.ts         # Core execution engine
│       ├── claude-provider.ts     # Anthropic Claude LLM backend
│       ├── mcp-manager.ts         # MCP server connections
│       ├── mcp-registry.ts        # Built-in server catalog (12 servers)
│       └── ...                    # Environment, values, config, plugins, etc.
├── tests/                         # 12 test suites, 319+ tests
├── examples/                      # 7 runnable .orch scripts
├── docs/
│   ├── specification.md           # Full language spec with EBNF grammar
│   └── ARCHITECTURE.md            # Runtime architecture and data flow
├── QUICKSTART.md                  # 5-minute setup guide
├── CLAUDE.md                      # LLM context for AI assistants
├── CONTRIBUTING.md
└── LICENSE

Specification

The complete language specification lives at docs/specification.md. It covers:

• Core syntax, variables, and operators
• 30+ reasoning macros (analysis, critique, synthesis, communication, generative)
• Control flow including parallel fork/join
• Tag system for behavior modification
• Meta operations (confidence, checkpoints, reflection)
• MCP and plugin integration
• Agent composition and multi-agent pipelines
• Error model with retry/fallback semantics
• Formal EBNF grammar

Status

Orchid v0.1.0 — the language design is stabilizing and the reference interpreter is fully functional.

What works today:

• Complete lexer, parser, and runtime interpreter
• 30+ reasoning macros powered by Claude API
• MCP tool integration with 12 built-in servers (filesystem, GitHub, Brave Search, memory, etc.)
• Parallel fork execution, confidence-gated control flow, agents and macros
• Sandbox mode with rate limiting and prompt sanitization
• Plugin system for JS/TS extensions
• npm registry search for discovering MCP servers
• Live terminal status spinner during execution
• 319+ tests across 12 test suites

What's coming: VS Code syntax highlighting, streaming responses, runtime benchmarks, more providers.

Contributing

See CONTRIBUTING.md for guidelines. The most valuable contributions right now:

• Feedback on the spec - Does the syntax make sense? What's confusing?
• Real-world use cases - What workflows would you write in Orchid?
• New providers - OpenAI, local models, etc.
• Tooling - Syntax highlighting, linters, formatters

License

MIT

Orchid is an open specification. Contributions, feedback, and implementations are welcome.