From fd9df3ffa4816cba1467fd71be4b35d6a6d663f5 Mon Sep 17 00:00:00 2001
From: Egor Aristov <ef@efprojects.com>
Date: Sat, 28 Mar 2026 21:14:11 +0300
Subject: [PATCH] agents.md

---
 AGENTS.md | 66 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 66 insertions(+)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..2d59706
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,66 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+**kitten-ipc** is a cross-language IPC (inter-process communication) framework. It consists of two parts:
+
+1. **`kitcom`** — a code generator CLI that parses annotated source files and generates IPC stub code for the other language
+2. **`lib/`** — runtime IPC libraries (Go and TypeScript) that handle the actual communication over Unix domain sockets using newline-delimited JSON messages
+
+The workflow: annotate structs/classes with `kittenipc:api` (Go) or `@kittenipc api` (TS), run `kitcom` to generate remote API stubs, then use the runtime library (`ParentIPC`/`ChildIPC`) to make cross-process calls.
+
+## Build & Test Commands
+
+```bash
+# Go workspace covers: kitcom, lib/golang, example/golang
+go build ./kitcom              # build the code generator
+go test ./lib/golang/...       # run runtime library tests
+go test ./kitcom/...           # run kitcom tests
+go test ./...                  # run all tests
+
+# Run a single test
+go test ./lib/golang/... -run TestName
+
+# Code generation (from example/)
+cd example && make ipc
+
+# kitcom usage
+kitcom -src path/to/source -dest path/to/output [-pkg packageName]
+# -pkg is required when generating Go output
+```
+
+## Architecture
+
+### Code Generator (`kitcom/`)
+
+- `main.go` — CLI entry point; selects parser/generator by file extension
+- `internal/api/` — language-neutral API model (`Api` → `Endpoint` → `Method` → `Val` with types: int, string, bool, blob)
+- `internal/golang/` — Go parser (`goparser.go`) reads `// kittenipc:api` annotations; Go generator (`gogen.go`) emits remote API stubs
+- `internal/ts/` — TypeScript parser (`tsparser.go`) reads `@kittenipc api` JSDoc annotations; TS generator (`tsgen.go`) emits stubs
+- `internal/tsgo/` — vendored subset of a Go-based TypeScript parser (scanner, AST, etc.)
+- `internal/common/` — shared parser/writer utilities
+
+### Runtime Library (`lib/`)
+
+**Go** (`lib/golang/`):
+- `parent.go` — `ParentIPC`: spawns a child process, listens on a Unix socket, accepts connection
+- `child.go` — `ChildIPC`: connects to parent's socket (path passed via `--ipc-socket` arg)
+- `common.go` — shared IPC logic: message send/receive, method dispatch via reflection, call tracking
+- `serialize.go` — type serialization/deserialization (handles blob as base64)
+- `protocol.go` — message format: `Message{Type, Id, Method, Args, Result, Error}`
+
+**TypeScript** (`lib/ts/`): mirror of the Go runtime
+
+### IPC Protocol
+
+- Transport: Unix domain socket, newline-delimited JSON
+- Two message types: `MsgCall` (1) and `MsgResponse` (2)
+- Methods are addressed as `EndpointName.MethodName`
+- Parent creates socket → starts child process → child connects back
+- Bidirectional: both sides can call methods on the other
+
+## Go Workspace
+
+Uses `go.work` with three modules: `kitcom`, `lib/golang`, `example/golang`.