{"id":50229259,"url":"https://github.com/Yukaii/ykmx","last_synced_at":"2026-06-12T09:01:07.118Z","repository":{"id":339900831,"uuid":"1156774749","full_name":"Yukaii/ykmx","owner":"Yukaii","description":"Yukai's take on terminal multiplexer","archived":false,"fork":false,"pushed_at":"2026-03-03T00:48:39.000Z","size":1078,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-03T03:49:50.500Z","etag":null,"topics":["bun","libghostty","plugin","terminal-multiplexer","zig"],"latest_commit_sha":null,"homepage":"","language":"Zig","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Yukaii.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-13T03:15:27.000Z","updated_at":"2026-03-03T00:48:43.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Yukaii/ykmx","commit_stats":null,"previous_names":["yukaii/ykmx"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Yukaii/ykmx","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Yukaii%2Fykmx","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Yukaii%2Fykmx/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Yukaii%2Fykmx/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Yukaii%2Fykmx/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Yukaii","download_url":"https://codeload.github.com/Yukaii/ykmx/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Yukaii%2Fykmx/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34199516,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-11T02:00:06.485Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bun","libghostty","plugin","terminal-multiplexer","zig"],"created_at":"2026-05-26T18:00:25.034Z","updated_at":"2026-06-12T09:01:07.113Z","avatar_url":"https://github.com/Yukaii.png","language":"Zig","funding_links":[],"categories":["Terminal Apps \u0026 Clients"],"sub_categories":[],"readme":"# ykmx\n\nExperimental terminal multiplexer in Zig, designed for modern terminal workflows (Ghostty + `zmx`) with tiling layouts, tabs, popups, mouse interactions, and plugin-extensible behavior.\n\n[![asciicast](https://asciinema.org/a/792060.svg)](https://asciinema.org/a/792060)\n\n## Current Status\n\n- Active prototype (`0.1.0-dev`)\n- Runtime loop works as the default mode\n- Built-in compatibility checks and manual soak scripts are included\n\n## Features\n\n- Multiple layouts: `vertical_stack`, `horizontal_stack`, `grid`, `paperwm`, `fullscreen`\n- Tabs/workspaces with window movement between tabs\n- Popup shell and panel controls\n- Scrollback mode with search/navigation\n- Mouse modes: `hybrid`, `passthrough`, `compositor`\n- Optional plugin host (Bun-based process model)\n- Optional plugin layout backend (`layout_backend=plugin`)\n\n## Requirements\n\n- Zig `0.15.2` or newer (project minimum)\n- A POSIX-like environment (macOS/Linux)\n- Optional:\n  - `zmx` for session attach/detach workflow\n  - `bun` for TypeScript plugin examples\n  - Ghostty for the compatibility path documented in this repo\n\n## Build and Run\n\n```bash\n# Build\nzig build\n\n# Run interactive runtime loop\nzig build run\n\n# Run tests\nzig build test\n\n# Run compatibility smoke checks\nzig build compat\n# or directly:\nscripts/compat/ci-smoke.sh\n```\n\nBinary output:\n\n- `./zig-out/bin/ykmx`\n\n## CLI\n\n```bash\nykmx --help\nykmx --version\nykmx --benchmark 300\nykmx --benchmark-layout 500\nykmx --smoke-zmx my-session\n```\n\n## Quick zmx Workflow\n\n```bash\n# Build first\nzig build\n\n# Start or attach to a session running ykmx\nzmx attach dev ./zig-out/bin/ykmx\n\n# Reattach later\nzmx attach dev\n```\n\nDetach from the current `zmx` client with `Ctrl+\\`.\n\n## Configuration\n\nConfig is loaded from the first existing file:\n\n- `$XDG_CONFIG_HOME/ykmx/config`\n- `$XDG_CONFIG_HOME/ykmx/config.toml`\n- `$XDG_CONFIG_HOME/ykmx/config.zig`\n- `$HOME/.config/ykmx/config`\n- `$HOME/.config/ykmx/config.toml`\n- `$HOME/.config/ykmx/config.zig`\n\nMinimal example:\n\n```toml\nlayout_backend=\"native\"\ndefault_layout=\"vertical_stack\"\nmaster_count=1\nmaster_ratio_permille=600\ngap=1\n\nshow_tab_bar=true\nshow_status_bar=true\nmouse_mode=\"hybrid\"\n\nplugins_enabled=false\nplugin_dir=\"$HOME/.config/ykmx/plugins\"\nplugins_dir=\"$HOME/.config/ykmx/plugins.d\"\n```\n\nReference config lives at `docs/examples/config.toml`.\n\n## Default Keybindings\n\nPrefix key is `Ctrl+G`.\n\n- Windows: `c` create, `x` close, `h/j/k/l` focus direction, `J/K` next/prev by index\n- Tabs: `t` new, `w` close active, `]`/`[` next/prev, `m` move focused window to next tab\n- Layout: `Space` cycle layout, `H/L` shrink/grow master ratio, `I/O` master count up/down\n- Popup/panels: `p` toggle popup shell, `Esc` close focused popup, `Tab` cycle popup focus\n- Scrollback: `u/d` page up/down, `s` toggle local scrollback navigation mode\n- Mouse mode: `M` cycle `hybrid -\u003e passthrough -\u003e compositor`\n- Quit ykmx: `q` (graceful shutdown of ykmx process)\n- Detach request: `\\`\n\n## Plugins\n\nWhen `plugins_enabled=true`, ykmx can run plugins as separate processes via:\n\n- `plugin.toml` `run=\"...\"` (generic runtime command in plugin cwd)\n- fallback: `bun run \u003cplugin_dir\u003e/index.ts`\n\nSupported plugin directory modes:\n\n- `plugin_dir=/abs/path/to/plugin` (single plugin)\n- `plugins_dir=/abs/path/to/plugins.d` (directory of plugin subfolders)\n- `plugins_dirs=[...]` (multiple roots)\n\nExample plugins are in `docs/examples/plugins.d/`:\n\n- `paperwm` (layout example)\n- `desktop-wm` (floating overlap + drag/resize + controls)\n- `popup-controls`\n- `sidebar-panel`\n- `bottom-panel`\n- `command-palette`\n- `theme-switch-command-palette`\n- `windows31-decoration-theme`\n- `retro-win31-theme`\n- `python-demo` (language-agnostic runtime via `plugin.toml run=...`)\n\n## Project Docs\n\n- Docs index / TOC: `docs/README.md`\n- Usage guide: `docs/usage.md`\n- Architecture overview: `docs/architecture.md`\n- Runtime flow: `docs/runtime-flow.md`\n- Module ownership map: `docs/module-map.md`\n- Refactor history: `docs/refactor-log.md`\n- Compatibility matrix and checklist: `docs/compatibility.md`\n- Implementation plan/context: `docs/plan.md`\n- Contributor/agent operating guide: `AGENTS.md`\n\n## Development Notes\n\n- This is an experimental codebase; interfaces and config keys may change.\n- For plugin behavior and NDJSON event/action protocol details, use `docs/usage.md` as the source of truth.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FYukaii%2Fykmx","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FYukaii%2Fykmx","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FYukaii%2Fykmx/lists"}