How to Integrate Orca with Existing C++ Projects: A Complete CLI-Based Guide

Orca integrates with C++ projects through its command-line interface (CLI), which communicates with the runtime via IPC sockets and returns structured JSON output that C++ applications can parse using standard subprocess techniques.

The stablyai/orca repository provides a runtime and skill architecture designed for AI-assisted development workflows. To integrate Orca with existing C++ projects, developers leverage the orca CLI tool, which exposes all runtime functionality through subprocess calls and JSON responses, eliminating the need for language-specific bindings or complex API integrations.

Understanding the Orca Architecture

CLI-First Design Pattern

Every Orca capability is exposed through the CLI, as documented in skills/orca-cli/SKILL.md. The runtime (an Electron/Node.js process) manages worktrees, terminals, and browser automation, while the CLI forwards commands through a local IPC channel. This design ensures that any language capable of spawning subprocesses—including C++—can fully control the Orca runtime.

Inter-Process Communication Mechanism

The CLI communicates with the runtime using platform-specific sockets. On macOS and Linux, it uses Unix domain sockets located at $HOME/.orca/socket. On Windows, it uses named pipes at \\.\pipe\orca. The socket path is available via the ORCA_SOCKET environment variable, allowing your C++ application to detect the runtime location dynamically.

Setting Up the Integration Environment

Installing the CLI

Enable the Orca CLI through the desktop application settings. Once enabled, the binary is available at:

• macOS/Linux: /usr/local/bin/orca
• Windows: C:\Program Files\Orca\orca.exe

Verify installation by running orca --version from your terminal.

C++ Language Detection

Orca automatically detects C++ files using the extension mapping in src/renderer/src/lib/language-detect.ts. Standard extensions like .cpp, .hpp, .cc, and .h are recognized without additional configuration.

Implementing the Integration Workflow

Integrating Orca with a C++ project follows a five-step pattern:

1. Create a worktree to register your project directory with the Orca runtime
2. Open a terminal within that worktree to execute commands
3. Send build commands to the terminal via the CLI
4. Wait for process completion using the built-in wait functionality
5. Read the terminal output to capture build logs, errors, or results

All commands support the --json flag, which returns deterministic output suitable for programmatic parsing.

Cross-Platform CLI Implementation

The following table summarizes platform-specific details for C++ integration:

Platform	CLI Path	IPC Mechanism	Socket Location
macOS	/usr/local/bin/orca	Unix domain socket	$HOME/.orca/socket
Linux	/usr/local/bin/orca	Unix domain socket	$HOME/.orca/socket
Windows	C:\Program Files\Orca\orca.exe	Named pipe	\\.\pipe\orca

Your C++ code should check the ORCA_SOCKET environment variable first, falling back to the default paths above if the variable is unset.

Complete C++ Integration Example

The following example demonstrates registering a worktree, executing a build command, and retrieving output using standard C++ libraries and the nlohmann/json library for parsing:

#include <cstdio>
#include <memory>
#include <stdexcept>
#include <array>
#include <string>
#include <nlohmann/json.hpp>

using json = nlohmann::json;

// Helper function to execute shell commands and capture stdout
std::string exec(const std::string& cmd) {
    std::array<char, 4096> buffer{};
    std::string result;
    std::unique_ptr<FILE, decltype(&pclose)> pipe(popen(cmd.c_str(), "r"), pclose);
    if (!pipe) throw std::runtime_error("popen() failed!");
    while (fgets(buffer.data(), buffer.size(), pipe.get())) {
        result += buffer.data();
    }
    return result;
}

int main() {
    const std::string projectPath = "/home/user/my_cpp_project";

    // Step 1: Register the worktree
    std::string createWtCmd = "orca worktree create --path " + projectPath + " --json";
    json wtInfo = json::parse(exec(createWtCmd));
    std::string worktreeHandle = wtInfo["handle"];

    // Step 2: Open a terminal within the worktree
    std::string createTermCmd = "orca terminal create --title \"build-term\" --json";
    json termInfo = json::parse(exec(createTermCmd));
    std::string termHandle = termInfo["handle"];

    // Step 3: Send the build command to the terminal
    std::string buildCmd = "orca terminal send --terminal " + termHandle +
                           " --input \"cd " + projectPath + " && make -j$(nproc)\"";
    exec(buildCmd);

    // Step 4: Wait for the build process to finish (10 minute timeout)
    std::string waitCmd = "orca terminal wait --terminal " + termHandle +
                          " --for exit --timeout-ms 600000 --json";
    json waitResult = json::parse(exec(waitCmd));

    // Step 5: Read the complete terminal output
    std::string readCmd = "orca terminal read --terminal " + termHandle +
                          " --cursor 0 --limit 10000 --json";
    json log = json::parse(exec(readCmd));
    std::cout << "Build output:\n" << log["text"] << std::endl;

    return 0;
}

This implementation uses popen to invoke the CLI, but you can substitute this with std::system, Boost.Process, or your preferred subprocess library. The --json flag ensures all responses are machine-parseable.

Key Source Files and References

Understanding these source files helps when debugging integration issues:

• skills/orca-cli/SKILL.md — Complete CLI reference documenting all sub-commands and JSON schemas
• src/renderer/src/lib/language-detect.ts — Language detection logic that maps file extensions to Monaco editor identifiers
• src/main/cli/ — Generated Node.js entry point for the CLI (compiled to out/cli/index.js)

Summary

• Orca uses a CLI-first architecture that requires no native C++ bindings or linkage
• All runtime communication occurs via IPC sockets (Unix sockets on macOS/Linux, named pipes on Windows) abstracted behind the CLI
• Every CLI command supports --json output for structured data exchange with C++ applications
• C++ file detection is automatic via the mapping in src/renderer/src/lib/language-detect.ts
• Integration requires only standard subprocess capabilities available in any C++ environment

Frequently Asked Questions

Do I need to link against Orca libraries to integrate with C++?

No. Orca does not provide or require C++ libraries. Integration occurs entirely through subprocess calls to the orca CLI executable. This approach ensures compatibility across different compilers and build systems without managing binary dependencies or ABI compatibility issues.

How does the CLI locate the running Orca runtime?

The CLI first checks the ORCA_SOCKET environment variable for the socket path. If unset, it falls back to default locations: $HOME/.orca/socket on macOS and Linux, or \\.\pipe\orca on Windows. Ensure the Orca desktop application is running before invoking CLI commands from your C++ code.

Can I integrate Orca with CMake or other build systems?

Yes. Use CMake's execute_process command, Makefile $(shell ...) functions, or your build system's equivalent to invoke the Orca CLI during the build process. Parse the JSON output to conditionally trigger rebuilds, run tests, or extract compilation errors for IDE integration.

What is the performance overhead of using CLI subprocess calls?

The overhead is minimal for build automation and development workflows. The CLI binary is lightweight and communicates with the runtime via local IPC (not network sockets). For high-frequency operations, you can maintain a persistent terminal session using orca terminal create and reuse the handle across multiple commands.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}