Tachikoma 🕷️ — One Swift API, many models

!Tachikoma banner

Tachikoma is a Swift package for generating and streaming text, using vision and tools, and building realtime voice or agent workflows across hosted and local AI providers. It is for Swift applications that need one typed, concurrency-safe interface instead of provider-specific clients.

Install

Add Tachikoma with Swift Package Manager:

platforms: [
    .macOS(.v14),
    .iOS(.v17),
],
dependencies: [
    .package(url: "https://github.com/openclaw/Tachikoma.git", from: "0.6.0"),
],
targets: [
    .target(name: "MyApp", dependencies: [
        .product(name: "Tachikoma", package: "Tachikoma"),
    ]),
]

Tachikoma requires Swift 6.2. Its declared Apple deployment targets are macOS 14, iOS 17, tvOS 17, watchOS 10, and visionOS 1; Linux builds are covered by CI.

Quick start

Provide a credential for the model you select—OPENAI_API_KEY for this example—then generate a response:

import Tachikoma
let answer = try await generate(
    "Write a haiku about Swift.",
    using: .openai(.gpt55)
)
print(answer)

The convenience API resolves credentials from the environment or TKAuthManager. Network calls require access to the selected provider.

Stream responses

stream returns an AsyncThrowingStream of provider-neutral text deltas:

import Tachikoma
let response = try await stream(
    "Explain actors in Swift.",
    using: .openai(.gpt55)
)
for try await delta in response {
    print(delta.content ?? "", terminator: "")
}

Use tools

Define a typed tool and pass it to generateText. Tachikoma executes tool calls and feeds their results back to the model for up to maxSteps steps.

import Tachikoma
let add = createTool(
    name: "add",
    description: "Add two integers",
    parameters: [
        .init(name: "a", type: .integer, description: "First value"),
        .init(name: "b", type: .integer, description: "Second value"),
    ],
    required: ["a", "b"]
) { arguments in
    let a = try arguments.integerValue("a")
    let b = try arguments.integerValue("b")
    return AnyAgentToolValue(int: a + b)
}
let result = try await generateText(
    model: .openai(.gpt55),
    messages: [.user("Use the add tool for 123 + 456.")],
    tools: [add],
    maxSteps: 3
)
print(result.text)

Choose a provider

The built-in catalog covers OpenAI, Anthropic, Google Gemini, xAI, MiniMax, Kimi, Mistral, Groq, Ollama, and LM Studio. Tachikoma also accepts custom OpenAI-compatible and Anthropic-compatible endpoints. See the model catalog for current enum cases, model IDs, defaults, and provider notes.

Common hosted providers read these environment variables:

| Provider | Variable | | --- | --- | | OpenAI | OPENAI_API_KEY | | Anthropic | ANTHROPIC_API_KEY | | Google Gemini | GEMINI_API_KEY or GOOGLE_API_KEY | | xAI | X_AI_API_KEY, XAI_API_KEY, or GROK_API_KEY | | MiniMax | MINIMAX_API_KEY | | Kimi | MOONSHOT_API_KEY or KIMI_API_KEY |

Use TKAuthManager when credentials should come from Tachikoma's stored profile instead. Hosts can change that profile root with TachikomaConfiguration.profileDirectoryName.

Modules

The package separates optional surfaces so applications only link what they use:

| Product | Purpose | | --- | --- | | Tachikoma | Core models, generation, streaming, vision, and tools | | TachikomaAgent | Conversations, sessions, and agent workflows | | TachikomaAudio | Transcription, text-to-speech, and realtime audio | | TachikomaMCP | Model Context Protocol integration |

Add an optional product beside Tachikoma in the target dependencies and import its module where needed.

Documentation

• Model catalog
• Architecture
• MCP integration
• Realtime voice and Harmony
• Local models with LM Studio
• Azure OpenAI

Development

git clone https://github.com/openclaw/Tachikoma.git
cd Tachikoma
swift build
TACHIKOMA_TEST_MODE=mock TACHIKOMA_DISABLE_API_TESTS=true swift test --parallel

See CONTRIBUTING.md for the contribution guide and docs/testing.md for test modes and provider integration tests.

License

MIT. See LICENSE.