tako

README

Tako

A Go TUI framework without the duct tape.
You handle the pixels. Tako handles DI, events, routing, and plugins.

[!WARNING] Experimental / Pre-Release Tako is currently in early development (v0.x.x). It is not yet ready for production use. The architecture and API contracts may experience breaking changes without warning as we refine the core design.

---

Why Tako?

Most Go TUI libraries draw boxes on screen. Tako handles how your app talks to itself — so your terminal app doesn't turn into a 3000-line main.go nobody wants to touch.

• UI-Agnostic — Use Bubble Tea, tview, tcell, or anything. Implement one interface (contracts.UIRenderer) and you're set.
• Clean Architecture — Service container, plugins, event bus. No global state, no spaghetti imports.
• Dual Kernel — Build CLI commands and interactive TUIs from the same codebase. Tako picks the right mode automatically.

Features

Feature	Description
Service Container	IoC with Singleton, Lazy, Transient bindings + closure injection
Plugin System	DAG-based dependency resolution with isolated lifecycle
Key & Mouse Routing	Focus stack with zone-scoped input dispatch
Event Bus + RPC	Pub/sub and request-response between plugins
Reactive State	Observable state with TTL, LRU eviction, debounced observers
Overlay System	Managed modal stack with focus trapping
CLI Commands	Built-in + custom commands with middleware pipeline
Hooks	Decoupled render slots for UI composition
Scheduler	Background jobs with callbacks
Developer Tools	Live inspector, time-travel replay, hot reload
Theming & i18n	Runtime theme switching and locale support
KV Storage	Persistent JSON-backed key-value store

Quick Start

mkdir myapp && cd myapp
go mod init myapp
go get gettako.dev/tako
go get gettako.dev/tako/pkg/adapter/ui/bubbletea

package main

import (
	"log"

	"gettako.dev/tako"
	"gettako.dev/tako/contracts"
	"gettako.dev/tako/pkg/adapter/ui/bubbletea"
)

type Layout struct{}

func (l *Layout) ID() string                        { return "dashboard" }
func (l *Layout) Render() any                       { return "Hello, Tako! Press ctrl+c to exit.\n" }
func (l *Layout) RegisterKeys(contracts.KeyManager) {}

// Init demonstrates Tako's built-in service injection
func (l *Layout) Init(app contracts.Application) {
	app.Logger().Info("Dashboard layout initialized!")
}

func main() {
	app := tako.NewApp()

	// Mount the Bubble Tea adapter
	app.Mount(bubbletea.NewAdapter(app.Context(), nil))

	// Set your root layout
	app.UI().Layout(&Layout{})

	if err := tako.Run(app); err != nil {
		log.Fatal(err)
	}
}

go run .

Every Tako app also works as a CLI — no extra setup:

go run . help
go run . version
go run . status

How It Works

┌─────────────────────────────────────────────────┐
│              Your Layout & Views                │  ← You work here
├─────────────────────────────────────────────────┤
│           Hooks & Overlays                      │
├─────────────────────────────────────────────────┤
│      Plugins (most app logic lives here)        │
├─────────────────────────────────────────────────┤
│     Event Bus · RPC Bus · State Manager         │
├─────────────────────────────────────────────────┤
│           Service Container                     │
├─────────────────────────────────────────────────┤
│         Bootstrap & Lifecycle                   │
└─────────────────────────────────────────────────┘

You bring the renderer. Tako wires everything else — key routing, events, overlays, and plugins all kick in automatically.

Demos

All runnable examples and cookbook recipes are maintained in the gettako/demo repository.

Demo	What it shows
01-todo	Full CRUD with state, overlays, and keybindings
02-dashboard	Multi-panel layout with live data
03-time-travel	Event recording and replay
04-mouse	Hitbox-based mouse routing
05-overlays	Modal stack management
06-plugins	Plugin lifecycle and isolation
07-communication	Inter-plugin event bus
08-services	Service container patterns
09-cli	CLI commands and middleware
10-theming	Runtime theme switching
11-state	Reactive state management
12-inter-plugin	RPC bus between plugins
13-native-bubbles	Using native Bubble Tea components

To try them out, clone the demo repository:

git clone https://github.com/gettako/demo.git tako-demo
cd tako-demo/01-todo
go run .

Documentation

Full documentation is available at gettako.dev.

• Overview — What Tako is and how it fits together
• Quick Start — Running app in under a minute
• Installation — Detailed setup guide
• Architecture — Boot sequence and service container
• Core Concepts — Routing, focus, hooks
• Plugin System — Building isolated features
• API Reference — Complete contract definitions

Requirements

• Go 1.23 or later
• A terminal emulator with ANSI support
• No CGO dependencies — runs anywhere Go compiles

Contributing

We welcome contributions! Please read CONTRIBUTING.md for guidelines on how to get started, coding standards, and our commit conventions.

License

Tako is released under the MIT License.

---

_{Built with 🐙 by GetTako}

Documentation

Overview

Package tako provides the main entry points for the Tako framework.

Index

• func NewApp() *foundation.Application
• func Run(app *foundation.Application, args ...string) error

Functions

func NewApp

func NewApp() *foundation.Application

NewApp is a convenience wrapper to create a new Foundation Application.

func Run

func Run(app *foundation.Application, args ...string) error

Run boots the application and starts the appropriate Kernel based on provided arguments. If no arguments are provided, it defaults to parsing os.Args[1:].