MikuCode

MikuCode is a macOS coding-agent desktop with an integrated local PTY. One transparent, persistent NSPanel owns both states: the idle panel shows Miku on the display under the pointer, and the active panel fills the display with a dark sky-blue speech-bubble workspace and Miku on the right.

Behavior

• The PTY output view is selectable and receives keyboard input directly.
• Miku stays still and front-facing in her idle area. Hovering crossfades to an attentive gaze and reveals a small terminal speech bubble; selecting either Miku or that bubble opens the full terminal in the same panel.
• The expanded workspace uses the default MikuCode theme with a compact miku-code header, one embedded-terminal toggle, and one close button. The coordinator owns one local PTY, transcript, current directory, and persisted session snapshot. Selecting the expanded Miku or the close button returns the same running app to its small idle Miku without sending it behind other windows; it returns to the desktop layer only after the app loses focus, and never quits MikuCode.
• The agent workspace starts with a centered MikuCode mark and a focused prompt composer. Choose Codex or Claude plus Plan, Accept, or Auto; the request is written to the integrated PTY only after the local terminal can accept it. The terminal button expands or hides that same embedded PTY below the conversation—no second window is created.
• Printable keys, control sequences, paste, resize, paging, find, clear, and interrupt use terminal keyboard actions. Command-F opens a compact transient finder inside the terminal bubble; Command-G and Shift-Command-G move between case-insensitive results, including results on other output pages. There are no permanent toolbars, buttons, status chips, or demo controls.
• Command-W closes the active presentation and returns the same panel to the transparent idle overlay.
• The shell starts in ~/Desktop when that directory exists, stops and drains on exit, and persists a bounded display snapshot.

The application does not launch another terminal application, post global keyboard events, or create a second window. The bundled companion art is original application artwork.

Architecture

The Swift Package Manager executable targets macOS 14 or later and has no third-party runtime dependencies.

The responsibility-oriented source layout and dependency rules are documented in ARCHITECTURE.md.

• MikuPanelCoordinator retains the single panel and applies the presentation state machine.
• AgentWorkspaceModel owns provider/approval selection and only records an agent prompt after its PTY write is confirmed.
• TerminalPanel embeds the coordinator-owned terminal pane.
• TerminalSessionModel owns one PTY lifecycle, buffering, persistence, and terminal updates.
• PTYProcess uses forkpty, a bounded non-blocking output/input path, and direct writes to its owned PTY master.
• ANSI parsing, selectable AppKit rendering, and optional Metal rendering preserve terminal output semantics and accessibility.

Build and test

export DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer
swift build -Xswiftc -warnings-as-errors
swift test -Xswiftc -warnings-as-errors
./scripts/build-app.sh
open build/MikuCode.app

MikuCode.app is the normal Dock-launchable application and does not keep a terminal emulator open. swift run MikuCodeApp is only a development launcher: it intentionally runs as a child of the terminal that invoked it, so its exit output remains in that terminal.

Requirements: macOS 14 or later, Swift 6 or later, and a local POSIX shell.

Scope

MikuCode provides one local shell and coding-agent prompts inside one panel. Remote connections, profiles, SSH, editor features, terminal tabs/splits, provider-specific session restoration, and complete terminal compatibility are out of scope. The protocol intentionally covers a focused subset of UTF-8, ANSI SGR, cursor movement, erasure, and bracketed paste behavior.

License

MikuCode is released under the MIT License.