How AI Tools Can Interact with Kaneo Programmatically: Complete TypeScript Client Guide

AI agents can fully automate Kaneo operations by importing the type-safe HTTP client from the @kaneo/libs package, which exposes strongly-typed methods for every API endpoint via Hono's RPC generator.

The open-source project management platform Kaneo (usekaneo/kaneo) provides a programmatic interface specifically designed for AI automation and third-party integrations. The official client library—published as @kaneo/libs—eliminates manual HTTP handling by exporting a strongly-typed client that maps directly to the server's OpenAPI specification, enabling AI tools to call endpoints with full TypeScript IntelliSense.

Architecture of the Kaneo Programmatic Client

Base URL Resolution with resolveApiBaseUrl

In packages/libs/src/api-url.ts, the resolveApiBaseUrl() function dynamically determines the API endpoint by reading the VITE_API_URL environment variable. If undefined, it falls back to http://localhost:1337 and guarantees the URL terminates with /api, ensuring consistent routing for all subsequent requests.

Per-Tab Session Identification

The client generates a random windowId for each browser context inside packages/libs/src/hono.ts, transmitting this value as the X-Kaneo-Window-Id header on every HTTP request. This mechanism allows the Kaneo server to distinguish between concurrent AI agent connections and maintain isolated session contexts.

Type-Safe RPC via Hono

The exported client singleton utilizes Hono's hc<AppType>() factory defined in packages/libs/src/hono.ts, where AppType represents the complete application type declared in apps/api/src/openapi.ts. This architecture provides compile-time type checking for every route—such as getWorkspaces, createTask, and uploadAvatar—while automatically injecting credentials: "include" to maintain cookie-based authentication sessions.

Implementing AI Automation with @kaneo/libs

Importing the Typed Client

To begin programmatic interaction, import the ready-made client singleton from the package entry point. The client is pre-configured and requires no manual instantiation.

import { client } from "@kaneo/libs";

Querying Workspace Data

AI tools can retrieve organizational context by calling client.getWorkspaces(), which returns a fully-typed response matching the Zod schemas defined in the API layer.

async function listWorkspaces() {
  const { data, error } = await client.getWorkspaces({});
  
  if (error) throw new Error(error.message);
  console.log("Available workspaces:", data);
  
  return data;
}

Creating Tasks Programmatically

The client.createTask() method accepts a project identifier and structured payload, enabling automated task generation from AI analysis pipelines without manual JSON construction.

async function createTask(projectId: string) {
  const { data, error } = await client.createTask({
    projectId,
    body: {
      title: "AI-generated documentation task",
      description: "Automatically created via programmatic interaction",
    },
  });
  
  if (error) throw new Error(error.message);
  console.log("Created task:", data);
  
  return data;
}

Uploading Binary Assets

For file operations, the client accepts base64-encoded buffers through client.uploadAvatar(), handling the contentType metadata required by the server's validation logic.

async function uploadAvatar(file: File) {
  const buffer = await file.arrayBuffer();
  const base64 = Buffer.from(buffer).toString("base64");

  const { data, error } = await client.uploadAvatar({
    body: { 
      contentType: file.type, 
      data: base64 
    },
  });
  
  if (error) throw new Error(error.message);
  console.log("Avatar URL:", data.url);
  
  return data;
}

Subscribing to Real-Time Events

Beyond REST operations, AI agents can establish WebSocket connections using the subscribe utility from @kaneo/libs/websocket to listen for live task updates without polling.

import { subscribe } from "@kaneo/libs/websocket";

function listenToTaskUpdates(taskId: string) {
  const ws = subscribe(`tasks/${taskId}`);
  
  ws.onmessage = (msg) => {
    console.log("Realtime update:", msg.data);
  };
  
  return ws;
}

Summary

• @kaneo/libs provides a zero-configuration, type-safe HTTP client generated from the server's OpenAPI specification in apps/api/src/openapi.ts.
• The resolveApiBaseUrl() function in packages/libs/src/api-url.ts handles environment-specific endpoint resolution with a localhost fallback.
• Every request automatically includes the X-Kaneo-Window-Id header for session isolation, managed transparently in packages/libs/src/hono.ts.
• AI tools can perform CRUD operations on workspaces, projects, and tasks using methods like getWorkspaces and createTask with full TypeScript autocomplete.
• Binary uploads require base64 encoding before transmission via client.uploadAvatar().
• Real-time capabilities are available through the separate subscribe WebSocket helper.

Frequently Asked Questions

What authentication method does the Kaneo client use?

The Kaneo client relies on cookie-based session authentication automatically managed by the browser or HTTP agent. The client configuration in packages/libs/src/hono.ts explicitly sets credentials: "include", ensuring cookies are transmitted with every request without manual header management.

Can the Kaneo client be used outside of a browser environment?

Yes, the @kaneo/libs package is pure TypeScript and functions in Node.js or edge runtime environments. While the windowId generation logic sounds browser-specific, the underlying HTTP client operates via standard fetch, making it suitable for server-side AI agents and automation scripts.

How does the Kaneo client handle type safety?

Type safety is enforced through Hono's RPC client (hc<AppType>), where AppType is the complete application type exported from apps/api/src/openapi.ts. Because the API routes are defined using createRoute() with Zod schemas in the backend, the frontend client receives generated types that prevent calling non-existent endpoints or sending malformed request bodies.

Is there a way to interact with Kaneo without using the official client?

While direct HTTP calls to the REST API are possible, the @kaneo/libs package is the recommended approach because it manages the X-Kaneo-Window-Id header, base URL resolution, and cookie credentials automatically. Bypassing the client requires manually implementing these behaviors, including reading VITE_API_URL and ensuring the /api suffix is present on all routes.

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