{"id":46332745,"url":"https://github.com/inbarr/tmax","last_synced_at":"2026-05-04T22:04:37.778Z","repository":{"id":338573509,"uuid":"1158119047","full_name":"InbarR/tmax","owner":"InbarR","description":"Cross-platform multi-terminal app with tiling layouts, floating panels, and a keyboard-driven workflow","archived":false,"fork":false,"pushed_at":"2026-05-02T23:03:50.000Z","size":6332,"stargazers_count":35,"open_issues_count":1,"forks_count":14,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-02T23:12:51.449Z","etag":null,"topics":["agent","ai","ai-agents","coding","developer-tools","electron","react","terminal","tiling-window-manager","typescript","xterm"],"latest_commit_sha":null,"homepage":"https://inbarr.github.io/tmax/","language":"TypeScript","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/InbarR.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-02-14T20:36:19.000Z","updated_at":"2026-05-02T23:03:54.000Z","dependencies_parsed_at":null,"dependency_job_id":"a59d1a14-0b3c-43e4-a646-985c98e7c231","html_url":"https://github.com/InbarR/tmax","commit_stats":null,"previous_names":["inbarr/tmax"],"tags_count":34,"template":false,"template_full_name":null,"purl":"pkg:github/InbarR/tmax","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/InbarR%2Ftmax","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/InbarR%2Ftmax/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/InbarR%2Ftmax/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/InbarR%2Ftmax/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/InbarR","download_url":"https://codeload.github.com/InbarR/tmax/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/InbarR%2Ftmax/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32626502,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-04T10:08:07.713Z","status":"ssl_error","status_checked_at":"2026-05-04T10:08:02.005Z","response_time":58,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["agent","ai","ai-agents","coding","developer-tools","electron","react","terminal","tiling-window-manager","typescript","xterm"],"created_at":"2026-03-04T18:06:40.043Z","updated_at":"2026-05-04T22:04:37.772Z","avatar_url":"https://github.com/InbarR.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/icon.png\" alt=\"tmax logo\" width=\"128\" /\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003etmax\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003eA powerful cross-platform multi-terminal app with tiling layouts, floating panels, and a keyboard-driven workflow.\u003c/p\u003e\n\nBuilt with Electron, React, TypeScript, xterm.js, and node-pty.\n\n![Windows](https://img.shields.io/badge/Windows-0078D6?logo=windows\u0026logoColor=white) ![macOS](https://img.shields.io/badge/macOS-000000?logo=apple\u0026logoColor=white) ![Linux](https://img.shields.io/badge/Linux-FCC624?logo=linux\u0026logoColor=black) ![Electron](https://img.shields.io/badge/Electron-30-47848F) ![TypeScript](https://img.shields.io/badge/TypeScript-5-3178C6)\n\n![tmax Screenshot](assets/screenshot.png)\n\n## Features\n\n**Multiple Terminals in One View**\n- Tiling layout with horizontal/vertical splits (binary tree, like tmux)\n- Floating panels that can be dragged, resized, and maximized\n- Equalize all panes to the same size with one shortcut\n- Status indicators per pane (green = active, grey = idle, red = error)\n- Focused pane highlighted with green-tinted title bar\n\n**Grid View Mode**\n- Toggle between Focus (single terminal) and Grid layout (`Ctrl+Shift+F`)\n- Grid auto-arranges terminals: 2x2, 3x2, etc. based on terminal count\n- Cycle grid column count with `Ctrl+Shift+L` (1-col stack, 2-col, 3-col, ...)\n- Fully resizable dividers in grid mode\n\n**Tab Groups**\n- Group related tabs with shared colors and collapsible headers\n- Right-click tab \u003e Add to Group (supports multi-select with Ctrl+click)\n- Group header right-click: Rename, Color picker, Ungroup All, Close All\n- Drag tabs between groups to reorganize\n- Group color tints both tabs and terminal pane backgrounds\n\n**AI Sessions Panel**\n- Monitor GitHub Copilot and Claude Code sessions in real-time (`Ctrl+Shift+C`)\n- Shows session status, summary, branch, repo, message/tool counts, and relative time\n- Click a session to resume it directly in a new terminal pane\n- Jump to any previous prompt in the terminal (`Ctrl+Shift+K`)\n- Filter tabs: All / Copilot / Claude Code\n- Search across sessions by name, branch, cwd, or summary\n- Desktop notifications when a Copilot session needs approval or input\n- WSL session discovery — sessions from WSL distros appear with a distro badge\n\n**File Explorer**\n- Sidebar file tree for the focused terminal's CWD (`Ctrl+Shift+X`)\n- Breadcrumb path navigation — click any segment to jump, or type a path directly\n- Navigate up, home (terminal CWD), or double-click folders to enter\n- File type icons (TS, JS, JSON, CSS, HTML, MD, PY, and more)\n- Single click to preview file content in a resizable side panel\n- Double click to open in default editor\n- Right-click menu: Preview, Open in Editor, Browse Here, CD Here, Copy Path\n- Filter input, show/hide dotfiles toggle, collapse all button\n- WSL filesystem support\n\n**Diff Review**\n- Built-in diff review overlay for code changes\n- File tree with filter search\n- Inline code review with annotations\n\n**Keyboard-Driven Workflow**\n- Command palette (`Ctrl+Shift+P`) with every action searchable\n- Jump to any terminal by name (`Ctrl+Shift+G`)\n- Pane hints for quick terminal switching (`Ctrl+Shift+J`)\n- Split, move, resize, and navigate — all from the keyboard\n- Every shortcut is fully configurable\n- macOS support: all Ctrl shortcuts work with Cmd, UI shows native symbols (⌘/⌥)\n\n**Modern Tab Bar**\n- Rounded pill-style tabs with subtle borders\n- Hide/show tab bar (`Ctrl+Shift+B`) for maximum screen space\n- Tab colors shown as bottom line indicator\n- Drag \u0026 drop to reorder or split\n\n**Appearance**\n- Font picker with all installed monospace fonts\n- Windows 11 Mica/Acrylic transparency (Appearance tab in Settings)\n- Background material and opacity controls\n- 10 built-in color themes or create your own\n- Dark title bar forced regardless of system theme\n\n**Drag \u0026 Drop**\n- Drag tabs to split panes (left/right/top/bottom indicators)\n- Drag to swap terminal positions\n- Drag to detach as floating panel\n- Visual drop zone labels showing exactly where the terminal will land\n\n**Session Management**\n- Auto-save/restore on close, crash, or reboot (saves every 5 seconds)\n- Named layouts: save and load terminal arrangements with titles and working directories\n- Startup commands per terminal — restored when loading a layout\n\n**WSL Integration**\n- Discover AI sessions running inside WSL distros\n- Sessions appear with distro badge in the AI Sessions panel\n- Resume WSL sessions in the correct distro and working directory\n- File explorer works with WSL filesystems\n- Terminal CWD tracking translates WSL paths for the Dirs panel\n\n**Configurable Everything**\n- Settings UI (`Ctrl+,`) with tabs for Terminal, Keybindings, Shells, Theme, and Appearance\n- Re-record any keybinding by clicking it\n- Add/remove shell profiles (PowerShell, CMD, WSL, or any executable)\n- Set default start folder globally or per shell\n\n## Tab Context Menu\n\nRight-click any tab for:\n- Rename\n- Split Right / Down\n- Focus / Split Mode\n- Float / Dock / Detach\n- Add to Group / Change Group\n- Tab Color picker\n- Set Startup Command\n- Hide Tab Bar\n- New Terminal (pick shell)\n- Close / Close Others / Close All\n\n## Download\n\nDownload the latest version from the [Releases page](https://github.com/InbarR/tmax/releases). Available for Windows (.exe installer + portable .zip), macOS (.dmg for Apple Silicon and Intel), and Linux (.deb, .rpm).\n\n### Troubleshooting Downloads\n\ntmax is an independent open-source project and isn't code-signed (certificates cost $300-600/year on Windows and $99/year on macOS). Your browser and operating system may warn you about the download. All of these warnings are cosmetic - nothing is wrong with the file itself. Here's how to get past each one.\n\n---\n\n#### 🪟 Windows\n\n**\"isn't commonly downloaded\" (Edge / Chrome)**\n\n![Edge SmartScreen warning](docs/screenshots/download-warn-edge.png)\n\nYour browser may silently pause the download and show the message above, or quietly stash it as `Unconfirmed *.crdownload` in your Downloads folder:\n\n![Unconfirmed crdownload](docs/screenshots/download-warn-crdownload.png)\n\nThis is [Microsoft SmartScreen's reputation filter](https://learn.microsoft.com/en-us/windows/security/operating-system-security/virus-and-threat-protection/microsoft-defender-smartscreen/) - new / niche installers trigger it regardless of content.\n\nTo allow the download:\n1. In the download warning, click the **⋯** menu and choose **Keep**. Edge then shows a second dialog:\n\n   ![Edge Keep confirmation](docs/screenshots/download-warn-edge-expanded.png)\n\n2. Click the **dropdown arrow** next to the red **Delete** button and choose **Keep anyway**.\n\n**\"Windows protected your PC\" on first launch**\n\nAfter installing, the first time you run tmax you'll see a blue \"Windows protected your PC\" dialog from SmartScreen. Click **More info** at the top, then **Run anyway** at the bottom.\n\n---\n\n#### 🍎 macOS\n\n**\"tmax is damaged and can't be opened\"**\n\n![macOS damaged warning](docs/screenshots/download-warn-macos.png)\n\nDespite what the dialog says, the app is fine. macOS requires apps to be signed with an Apple Developer certificate ($99/year). Since I'm not planning to pay that evil company 😏, you have to bypass the quarantine flag yourself. Click **Cancel** (not Move to Trash!) and run this in Terminal:\n\n```bash\nxattr -cr /Applications/tmax.app\n```\n\nThis clears the quarantine extended attribute so macOS skips the signature check. Open tmax normally afterwards.\n\nIf you installed to a different location, adjust the path (e.g. `~/Applications/tmax.app`).\n\n---\n\n## Building from Source\n\n### Prerequisites\n\n- Node.js 18+\n- npm\n- **Windows**: [Visual Studio 2022 Build Tools](https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2022) with \"Desktop development with C++\" workload (for node-pty native compilation). VS 2025+ is not yet supported by node-gyp — if you only have VS 2025, install the 2022 Build Tools alongside it and set `GYP_MSVS_VERSION=2022` before running `npm install`.\n- **macOS**: Xcode Command Line Tools (`xcode-select --install`)\n- **Linux**: `build-essential`, `python3`, `libx11-dev`, `libxkbfile-dev`\n\n### Install \u0026 Run\n\n```bash\ngit clone https://github.com/InbarR/tmax.git\ncd tmax\nnpm install\nnpm start\n```\n\n### Build Installer\n\n```bash\nnpm run build\n```\n\nOutput per platform:\n- **Windows**: `out/make/squirrel.windows/x64/tmax-\u003cversion\u003e Setup.exe`\n- **macOS**: `out/make/*.dmg`\n- **Linux**: `out/make/deb/x64/*.deb` and `out/make/rpm/x64/*.rpm`\n- **All**: portable `.zip`\n\n## Architecture\n\n```\nsrc/\n  main/           Electron main process\n    main.ts                     Window creation, IPC handlers\n    pty-manager.ts              node-pty lifecycle management\n    config-store.ts             electron-store config persistence\n    copilot-session-monitor.ts  Scans ~/.copilot/session-state/\n    copilot-session-watcher.ts  File watcher for Copilot sessions\n    copilot-events-parser.ts    Incremental JSONL parser for Copilot events\n    copilot-notification.ts     Desktop notifications for Copilot\n    claude-code-session-monitor.ts  Scans ~/.claude/projects/\n    claude-code-session-watcher.ts  File watcher for Claude Code sessions\n    claude-code-events-parser.ts    JSONL parser for Claude Code sessions\n    wsl-session-manager.ts      Manages session monitors for WSL distros\n    wsl-utils.ts                WSL distro detection and path translation\n    git-diff-service.ts         Git diff parsing for code review\n    version-checker.ts          Auto-update via GitHub releases\n    diag-logger.ts              Diagnostic logging for debugging\n  preload/        Secure IPC bridge (contextBridge)\n  renderer/       React UI\n    state/          Zustand store + binary tree / grid layout engine\n    components/     Terminal, TabBar, TilingLayout, FloatingPanel,\n                    CopilotPanel, FileExplorer, DiffReview,\n                    CommandPalette, Settings, etc.\n    hooks/          Keybindings, drag \u0026 drop, PTY helpers\n    utils/          Platform detection (macOS/Windows/Linux)\n    styles/         Global CSS (Catppuccin theme)\n  shared/         IPC channel constants, AI session types, diff types\n```\n\n**Key design decisions:**\n- Binary tree layout engine for tmux-style tiling with arbitrary splits\n- Zustand for state management (terminals, layout, focus, config)\n- `@dnd-kit` for structured drag \u0026 drop with per-pane drop zones\n- `node-pty` with ConPTY for native Windows terminal emulation\n- `contextIsolation: true` for Electron security\n- Session auto-save every 5s for crash recovery\n- Renderer heartbeat for freeze detection diagnostics\n\n## Configuration\n\nSettings are stored at:\n```\n%APPDATA%/tmax/tmax-config.json\n```\n\nYou can edit this file directly or use the Settings UI (`Ctrl+,`).\n\n### AI Session Commands\n\nThe commands used to resume Copilot and Claude Code sessions are configurable in **Settings \u003e Terminal**:\n\n| Setting | Default | Description |\n|---------|---------|-------------|\n| Copilot Command | `copilot` | Base command for Copilot sessions |\n| Claude Code Command | `claude` | Base command for Claude Code sessions |\n\nThis lets you use custom aliases or wrapper scripts. The configured command is invoked as `\u003ccommand\u003e --resume \u003csessionId\u003e`.\n\n## Contributing\n\nContributions are very welcome - bug reports, feature ideas, and pull requests all help make tmax better.\n\n\u003e **Use your personal GitHub account, not your org/EMU account** when filing issues or opening PRs. EMU accounts are typically blocked from interacting with public repos outside their enterprise.\n\n### Reporting bugs\n\nOpen an issue on the [GitHub tracker](https://github.com/InbarR/tmax/issues) with:\n- Your OS and tmax version (shown in the title bar / About)\n- Steps to reproduce\n- What you expected vs. what happened\n- Screenshots or a short screen recording if the bug is visual\n\n### Suggesting features\n\nFor larger ideas, open an issue first to discuss the shape of the change before writing code. Smaller polish PRs (typos, copy fixes, obvious bugs) can go straight to a PR.\n\n### Pull requests\n\n1. Fork the repo and create a branch off `main`.\n2. Set up the dev environment (see [Building from Source](#building-from-source)) and run `npm start` to verify the app launches.\n3. Make your change. Keep PRs focused - one feature or fix per PR.\n4. **Cross-platform compatibility is required.** tmax ships on Windows, macOS, and Linux. Use `isMac ? event.metaKey : event.ctrlKey` for primary modifiers, `formatKeyForPlatform()` for shortcut text in the UI, and avoid hardcoded paths or shell assumptions. See [`CLAUDE.md`](CLAUDE.md) for the full guidelines.\n5. Run the e2e test suite: `npm run test:e2e`. Add a Playwright spec under `e2e/` for any user-visible bug fix or new feature.\n6. Open the PR with a description of what changed and why, plus any UI screenshots.\n\n### Code style\n\n- TypeScript strict mode, React function components, Zustand for state.\n- No new dependencies without a clear reason - tmax keeps its dependency surface small.\n- Match the surrounding code's formatting (no separate formatter config to wrestle with).\n\n### Project management\n\nLarger work is tracked with [Backlog.md](https://github.com/MrLesk/Backlog.md) under `backlog/tasks/`. You don't need to use it to contribute, but if you're picking up an existing task, set its status to In Progress and assign yourself first (`backlog task edit \u003cid\u003e -s \"In Progress\" -a @your-handle`).\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finbarr%2Ftmax","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Finbarr%2Ftmax","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finbarr%2Ftmax/lists"}