Tama Link

Tama Link is a small local compatibility proxy between Tama and AI coding clients such as Codex, OpenCode, and Pi.

Tama can execute durable, asynchronous MCP work. Many coding clients either do not implement MCP Tasks yet or implement different subsets of the protocol. A client that only understands an ordinary blocking tool call cannot safely own Tama's durable execution lifecycle, and making Tama imitate every client would mix client compatibility concerns into the Tama server.

Tama Link keeps that boundary clean. It speaks the protocol expected by Tama on the upstream side and exposes exactly two ordinary MCP tools to the client:

Tool	Responsibility
submit	Start one allowed upstream Tama operation and return a durable submission identifier.
await	Wait for or inspect that submission and return progress or its terminal result.

The detailed and authoritative implementation contract is in wip/tama-link-specification.md.

Why a separate project?

Tama Link isolates three things that change at different speeds:

• Tama owns execution, authorization, and durable task state.
• Tama Link owns protocol negotiation, task correlation, polling, and the two-tool compatibility contract.
• Product integrations such as memovee-codex and memovee-opencode own installation, client configuration, skills, and client-specific progress UI.

This lets Tama adopt newer MCP standards without requiring every client to upgrade at the same time. It also lets client plugins improve presentation without duplicating authentication, polling, retry, or result semantics.

Codex / OpenCode / Pi
        |
        | submit / await
        v
    Tama Link
        |
        | negotiated MCP and durable task operations
        v
       Tama

Tama Link is intended to run on the user's machine as one Go binary. The Memovee CLI will install and configure it, while the client-specific Memovee packages will adapt its progress events to the UI their host supports.

Current status

Phase 1 of the implementation plan is complete. The CLI provides serve --profile <name>, reserved login and logout commands, and version [--json]. serve starts the STDIO MCP server, which advertises exactly submit and await. The Phase 1 foundation includes the validated profile/catalog model, encrypted SQLite submissions, secure keyring integration, idempotency, atomic terminal capture, cross-process leases, retention, and restart-safe local worker recovery. A named profile must exist in the Tama Link configuration directory before serve starts.

Phase 2's downstream handlers and upstream adapter are implemented, and the pinned TamaMCP fixture gate runs in CI. Live migrated-Tama acceptance has not passed. Fixture, mocked, and Compose pin results are not that gate. See wip/tama-link-specification/acceptance/phase-2.md.

Phase 3 adds the explicit interactive login and profile schema version 2: profiles now declare a non-empty, canonical scopes array that binds every authorization request, token response, and refresh. Version 1 profiles stay loadable for the non-interactive runtime but fail login with a migration error.

No client or installer should treat this revision as production ready.

Development

The project targets Go 1.25 and pins development tools with mise.

mise install
make check
make build

Run the MCP server over STDIO for a named profile:

go run ./cmd/tama-link serve --profile tama-app

Print build information:

go run ./cmd/tama-link version
go run ./cmd/tama-link version --json

A Codex-style STDIO registration invokes the same command, once per profile:

tama-app    -> tama-link serve --profile tama-app
tama-system -> tama-link serve --profile tama-system

Authorize an existing profile, or create one on a fresh machine:

go run ./cmd/tama-link login --profile tama-app
go run ./cmd/tama-link login --address https://tama.example --type app --yes

On an interactive terminal, login with no profile asks for a path-free Tama origin, an app or system type, and confirmation before opening the browser. --type defaults to app and derives /mcp/app or /mcp/system. Non-interactive creation requires --address and never prompts. The command does not replace an existing profile. The default path opens the authorization URL in the platform browser and waits on a bounded loopback callback. With --no-browser, or when the browser cannot be opened, the authorization URL is printed to standard output for a manual handoff; all other output goes to standard error. The first secure-keyring access may display an operating-system unlock prompt; interactive login allows up to two minutes to complete it, while unattended serve startup retains its five-second fail-fast probe. On Linux, Tama Link uses the desktop default keyring and does not create a separate Tama Link collection. Credentials stranded by an older build can be copied with tama-link repair --profile <name>; that command does not delete the old collections. Exit status is 0 for a committed and verified login, 1 for runtime and authorization failures, and 2 for usage or profile-contract errors, including a version 1 profile that has not been regenerated with scopes. logout --profile <name> remains a reserved command in this phase.

Branching

This repository uses Git Flow:

• main contains production releases;
• develop is the integration branch;
• feature branches start from develop as feature/<name>;
• release branches use release/<version>; and
• urgent fixes use hotfix/<name>.

See CONTRIBUTING.md for the validation workflow.

License

Licensed under the Apache License, Version 2.0. See LICENSE.