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

> Integrate Orca into your C++ projects using its CLI. This guide shows how to leverage IPC sockets and JSON output for seamless integration.

- Repository: [Stably/orca](https://github.com/stablyai/orca)
- Tags: how-to-guide
- Published: 2026-05-25

---

**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`](https://github.com/stablyai/orca/blob/main/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`](https://github.com/stablyai/orca/blob/main/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:

```cpp
#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`](https://github.com/stablyai/orca/blob/main/skills/orca-cli/SKILL.md) — Complete CLI reference documenting all sub-commands and JSON schemas
- [`src/renderer/src/lib/language-detect.ts`](https://github.com/stablyai/orca/blob/main/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`](https://github.com/stablyai/orca/blob/main/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`](https://github.com/stablyai/orca/blob/main/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.