| name | tachikoma-tui |
| description | Bootstrap guide for building a Tachikoma.jl TUI app. Load when asked to create, scaffold, or extend a terminal UI in Julia using Tachikoma, including any work that touches Model/update!/view, the app() loop, layouts, widgets, or KeyEvent / MouseEvent handling. Covers the minimal app skeleton and the sharp edges that cost the most round trips. |
Tachikoma.jl App Scaffolding
A reference for building a TUI in Tachikoma.jl. Covers the protocol every app implements, the layout primitives, the small set of widgets you reach for first, and the sharp edges that cost time when you hit them blind.
For anything not covered here, the canonical references are the published docs at kahliburke.github.io/Tachikoma.jl/dev and the bundled demos in the Tachikoma.jl repo. Treat this skill as the runway, not the manual.
1. Minimum viable app
Every Tachikoma app does three things: define a mutable Model, implement update! to react to events, and implement view to draw each frame. app(m) runs the loop.
using Tachikoma
@tachikoma_app
@kwdef mutable struct Counter <: Model
quit::Bool = false
tick::Int = 0
n::Int = 0
end
should_quit(m::Counter) = m.quit
function update!(m::Counter, evt::KeyEvent)
evt.key == :char && evt.char == 'q' && (m.quit = true)
evt.key == :escape && (m.quit = true)
evt.key == :char && evt.char == '+' && (m.n += 1)
evt.key == :char && evt.char == '-' && (m.n -= 1)
end
function view(m::Counter, f::Frame)
m.tick += 1
inner = render(Block(title="Counter"), f.area, f.buffer)
set_string!(f.buffer, inner.x + 1, inner.y + 1,
"n = $(m.n) [+/-]change [q]uit", tstyle(:primary))
end
app(Counter())
Three things to notice:
- The struct must be
mutable and subtype Model. update! mutates it in place.
@tachikoma_app brings the callback names (view, update!, should_quit, init!, cleanup!) into your namespace so your method definitions extend Tachikoma's, instead of shadowing them in a fresh namespace.app(m) enters the alt screen, raw mode, and mouse mode, then runs the 60fps loop. Ctrl+C exits regardless of what update! does.
2. The protocol
All callbacks dispatch on your model type. Only view and update! (or should_quit flag) are typically needed; the rest exist for less common cases.
| Callback | Required | Purpose |
|---|
view(m, f::Frame) | yes | Draw into f.buffer within f.area. Called each frame. |
update!(m, e::Event) | yes | React to input. Dispatch on KeyEvent, MouseEvent, TaskEvent. |
should_quit(m) | yes | Return true to exit the loop cleanly. |
init!(m, t::Terminal) | no | One-shot setup; terminal size is known here. |
cleanup!(m) | no | Teardown after the loop exits (terminal already restored). |
pre_render!(m) / post_render!(m) | no | Hooks immediately before/after view. |
task_queue(m) | no | Return a TaskQueue to enable spawn_task! / TaskEvent. |
recording_enabled(m) | no | Return false to disable Ctrl+R recording for this app. |
See architecture for the full lifecycle.
3. Events
update! is dispatched on three concrete event types. Define one method per type you care about.
KeyEvent — fields key::Symbol, char::Char, action::KeyAction.
Common key values: :char, :escape, :enter, :backspace, :tab, :backtab, :up, :down, :left, :right, :home, :end_key, :pageup, :pagedown, :delete, :insert, :f1 through :f12, :ctrl, :ctrl_c. For printable characters, key == :char and char holds the value. Match.jl is idiomatic for non-trivial dispatch:
using Match
function update!(m::MyApp, e::KeyEvent)
@match (e.key, e.char) begin
(:char, 'q') || (:escape, _) => (m.quit = true)
(:char, 'r') || (:enter, _) => reset!(m)
_ => nothing
end
end
MouseEvent — fields x::Int, y::Int (1-based screen coords), button, action, plus shift/alt/ctrl flags. Buttons include mouse_left, mouse_middle, mouse_right, mouse_scroll_up, mouse_scroll_down. Actions are mouse_press, mouse_release, mouse_drag, mouse_move. Store widget rects on the model and use contains(rect, e.x, e.y) for hit testing.
TaskEvent — fields id::Symbol, value::Any. Delivered when background work spawned via spawn_task!/spawn_timer! completes. Requires a task_queue(m) method. See the async docs.
4. Layout
Layouts are constraint-based and explicit. You divide a Rect into child rects using a vector of constraints.
| Constraint | Meaning |
|---|
Fixed(n) | Exactly n cells. |
Min(n) | At least n cells; grows if room remains. |
Max(n) | Up to n cells. |
Percent(p) | p% of the parent rect (integer 0-100). |
Fill(w=1) | Takes remaining space; w is the relative weight. |
Ratio(a, b) | a/b of the parent rect. |
rows = split_layout(
Layout(Vertical, [Fixed(1), Fixed(5), Fill(), Fixed(1)]),
f.area)
length(rows) < 4 && return # terminal may be too small
cols = split_layout(Layout(Horizontal, [Percent(30), Fill()]), rows[3])
Layouts nest freely: split horizontally, then split each column vertically. Use Layout(Vertical, [...]; spacing=1) to leave a row between children.
Geometry helpers worth knowing (all exported): inner(r) shrinks by 1 on every side, center(parent, w, h) returns a Rect of size w×h centered in parent, shrink(r, n) applies a uniform margin, bottom(r) and right(r) give the last row/column, anchor(parent, w, h; h=:center, v=:center) for corner placement.
5. Rendering primitives
Two ways to put characters on screen, both writing to f.buffer:
set_char!(buf, x, y, '█', tstyle(:primary))
set_string!(buf, x, y, "hello", tstyle(:accent))
Coordinates are 1-based: set_char!(buf, 1, 1, ...) writes the top-left cell. f.area.x and f.area.y are also 1-based.
For anything more complex, call a widget's render:
inner = render(Block(title="Stats"), f.area, buf)
# `inner` is the rect inside the border; draw widgets into it
render(Gauge(0.42; filled_style=tstyle(:primary)), inner, buf)
render(widget, rect, buf) returns the inner rect the widget consumed. For container widgets like Block, that's the space inside the border; for content widgets, it's usually the input rect unchanged. Construct stateless widgets fresh each frame with current data. Persist stateful widgets (see Section 7) on the model.
6. Styling
Use tstyle(name; bold=false, dim=false, italic=false, underline=false) keyed by a theme slot:
tstyle(:primary, bold=true)
tstyle(:text_dim)
tstyle(:error)
Available slots include :primary, :accent, :success, :warning, :error, :border, :title, :text, :text_dim, :background. The active theme controls the actual colors, so an app written with tstyle automatically adapts to all 24 bundled themes and to the user's Ctrl+\ theme switch. Avoid hard-coded Color256/ColorRGB unless drawing pure-aesthetic content.
7. The widgets you'll reach for first
Tachikoma ships 30+ widgets. Five cover most app scaffolds; for the rest see the widgets reference.
Block(title=..., border_style=...) — bordered container. Returns the inner Rect.
inner = render(Block(title="Logs", border_style=tstyle(:border)), area, buf)
StatusBar(left=[Span(...)], right=[Span(...)]) — single-row strip with left/right-aligned spans. Render into a Fixed(1) row, typically rows[end] or pinned to bottom(f.area).
render(StatusBar(
left=[Span(" [r]oll ", tstyle(:accent))],
right=[Span("[q]uit ", tstyle(:text_dim))],
), Rect(f.area.x, bottom(f.area), f.area.width, 1), buf)
Gauge(ratio; filled_style, empty_style, label="") — horizontal progress bar; ratio is 0.0..1.0. Reconstruct each frame.
SelectableList(items; selected=1, focused=true) — keyboard-navigable list. Stateful: store on the model. Use handle_key!(list, evt) to delegate arrow keys; read value(list) for the current item.
Form([FormField("Name", TextInput(...); required=true), ...]; tick) — labeled fields, Tab/Shift-Tab navigation, submit button, validation. Stateful: store on the model. Sync m.form.tick = m.tick each frame so cursors blink. handle_key!(m.form, evt) drives navigation; valid(m.form) and value(m.form) read the result.
For a fuller catalog: MarkdownPane, DataTable, Chart, BarChart, Sparkline, Calendar, Modal, TreeView, Checkbox, RadioGroup, DropDown, Button, TabBar, ScrollPane, Paragraph, BigText, CodeEditor, Canvas, BlockCanvas, PixelImage, FloatingWindow, WindowManager, TerminalWidget, REPLWidget, Separator.
8. Default key bindings
app(m) installs these automatically. Pass default_bindings=false to disable when an app needs the Ctrl+letter range for its own use.
| Key | Action |
|---|
Ctrl+C | Quit (always active, can't be disabled) |
Ctrl+G | Toggle mouse mode |
Ctrl+\ | Open theme selector |
Ctrl+A | Toggle animations |
Ctrl+S | Settings overlay |
Ctrl+? | Help overlay |
Ctrl+R | Start/stop .tach recording |
Ctrl+Y | Copy pane to clipboard |
9. Sharp edges
These are the mistakes that cost the most round trips. Most are not visible until they bite.
- Struct must be
mutable. update! mutates the model in place. An immutable struct fails with setfield! immutable struct the first time a key arrives.
@tachikoma_app (or explicit import Tachikoma: view, update!, should_quit) is required. Without it, function view(::MyModel, ...) defines a fresh view in your module instead of extending Tachikoma's, and the loop never sees it. Symptom: blank screen, no errors.- Reconstruct stateless widgets each frame, persist stateful ones.
Block, Gauge, Sparkline, BarChart, StatusBar, Paragraph, BigText, Modal, Separator are stateless: build them fresh in view. TextInput, TextArea, CodeEditor, DataTable, Form, SelectableList, TreeView, DropDown, Checkbox, RadioGroup, Button, ScrollPane, REPLWidget, TerminalWidget carry internal state (cursor, scroll, selection, focus); rebuilding them each frame resets it. Store these on the model.
- Coordinates are 1-based.
set_char!(buf, 1, 1, ...) is the top-left. So are f.area.x and f.area.y. Off-by-one bugs at the top edge usually trace to assuming 0-based.
split_layout returns fewer rects than constraints if the area is too small. Always guard: length(rows) < N && return before indexing. This happens routinely at app startup when the terminal hasn't reported a size yet, and when the user shrinks the window.- Stateful widgets carrying a
tick need it synced before render. Pattern: m.form.tick = m.tick (and same for any list/button with cursor animations) at the top of view. Without it, cursors and spinners freeze on the first value.
println and print from inside view/update! corrupt the screen. They write directly to the terminal while Tachikoma is composing the frame. Use @info/@debug/@warn (Tachikoma redirects logging through the recording channel) or wire on_stdout / on_stderr callbacks via app(m; on_stdout=..., on_stderr=...).- Don't
Pkg.activate inside init!. Activate the project before launching the app. Activating during init! causes Pkg side effects to compete with the render loop for the terminal.
- Wrap
app(m) in a function. A bare app(m) at top level blocks the REPL with no way to re-enter cleanly after exit. Standard pattern: function myapp(); app(MyModel()); end, then call myapp().
TerminalWidget and REPLWidget own a subprocess or PTY. Close them in cleanup!(m) (call close!(w) or pty_close!) or wrap your app(...) call in try/finally. Otherwise the child process leaks past app exit.Frame.area may not equal terminal size. It's the area the framework gave this view call; on resize events you'll see a different rect mid-frame. Always layout from f.area, never from a cached terminal size.
10. Where to look next
Reference docs (published at kahliburke.github.io/Tachikoma.jl/dev):
| Page | Topic |
|---|
| getting-started | Build-your-first-app walkthrough |
| architecture | Full lifecycle, Frame/Buffer internals |
| layout | Constraint semantics, ResizableLayout |
| widgets | Every widget with constructor signatures |
| events | Event types and dispatch in depth |
| styling | Themes, palettes, color helpers |
| async | TaskQueue, spawn_task!, spawn_timer! |
| animation | Tweens, springs, organic effects |
| canvas | Braille, block, and pixel rendering |
| testing | TestBackend for headless widget tests |
| recording | .tach format, record_app, SVG/GIF export |
Seed templates in the Tachikoma.jl repo, under demos/TachikomaDemos/src/:
clock.jl — minimal animation loop with BigText, Calendar, StatusBar. The cleanest "shape of a view" reference.form_demo.jl — Form with validators, FocusRing, submit detection.dashboard.jl — multi-widget layout, simulated data, nested split_layout.life.jl and mouse_demo.jl — init!-based canvas setup, mouse hit testing with contains.snake.jl — game loop with tick-driven simulation.
To run the demos locally, clone Tachikoma.jl, then from its root:
using Pkg
Pkg.activate("demos/TachikomaDemos")
Pkg.instantiate()
using TachikomaDemos
launcher()
