{"id":50821668,"url":"https://github.com/codejive/java-miniterm","last_synced_at":"2026-06-13T14:31:31.669Z","repository":{"id":356487222,"uuid":"1232322962","full_name":"codejive/java-miniterm","owner":"codejive","description":"Extremely minimal terminal library for Java. Designed to be as small as possible.","archived":false,"fork":false,"pushed_at":"2026-05-08T10:54:30.000Z","size":86,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-08T11:07:05.320Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/codejive.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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-05-07T20:18:04.000Z","updated_at":"2026-05-08T10:54:34.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/codejive/java-miniterm","commit_stats":null,"previous_names":["codejive/miniterm"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/codejive/java-miniterm","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codejive%2Fjava-miniterm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codejive%2Fjava-miniterm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codejive%2Fjava-miniterm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codejive%2Fjava-miniterm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/codejive","download_url":"https://codeload.github.com/codejive/java-miniterm/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codejive%2Fjava-miniterm/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34288662,"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-13T02:00:06.617Z","response_time":62,"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":[],"created_at":"2026-06-13T14:31:30.974Z","updated_at":"2026-06-13T14:31:31.662Z","avatar_url":"https://github.com/codejive.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# java-miniterm\n\n`miniterm` is a Java library that provides low-level terminal access. Its main selling point is that it is extremely small (**~25KB**), making it ideal for CLI tools and applications where keeping dependencies lightweight matters.\n\nTwo variants are available:\n- **[`miniterm`](miniterm/README.md)** — legacy implementation, works with Java 8+\n- **[`miniterm-ffm`](miniterm-ffm/README.md)** — modern implementation using the Foreign Function \u0026 Memory API, requires Java 22+\n\n**Philosophy** : these modules, and the project in general, have been expressly created to be as minimal as possible, it only offers the most essential functionality that is missing from Java to be able to use the features of a modern Terminal. Several other projects exist that do this as well, but they normally come with a whole bunch of other things that you might not need. `miniterm` on the other hand *only* does the work that you can't do with standard Java APIs. Everything else can be built on top.\n\nAnd then we have utility modules (the \"built on top\"):\n- **[`ansiparser`](ansiparser/README.md)** — compact ANSI escape sequence parser\n- **[`colors`](colors/README.md)** — terminal colour palette querying and setting\n- **[`mousetrack`](mousetrack/README.md)** — terminal mouse-tracking helpers and event parser\n- **[`termcap`](termcap/README.md)** — terminal capability detection\n\n**Acknowledgements** : `miniterm` is inspired by and has unashamedly copied ideas and code from [AEsh](https://github.com/aeshell/aesh-readline) and [Tamboui Panama backend](https://github.com/tamboui/tamboui/tree/main/tamboui-panama-backend).\n\n## Usage\n\n```java\nimport org.codejive.miniterm.Terminal;\n\npublic class Example {\n    public static void main(String[] args) throws Exception {\n        try (Terminal terminal = Terminal.create()) {\n            // Do terminal stuff here...\n        }\n    }\n}\n```\n\n### Get terminal size\n\n```java\nvar size = terminal.size();\nSystem.out.println(\"The size of the terminal is \" + size);\n```\n\n### Read key presses\n\n```java\nterminal.enableRawMode();\nwhile (true) {\n    int key = terminal.read(1000);\n    if (key == -1 || key == 3) { // Ctrl+C\n        break; // End of stream\n    } else if (key \u003e= 0) {\n        System.out.println(\"Key pressed: \" + key);\n    }\n}\n```\n\n### Read key presses \u0026 ANSI sequences\n\n```java\nterminal.enableRawMode();\nAnsiReader reader = new AnsiReader(() -\u003e terminal.read(-1));\nString seq;\nwhile ((seq = reader.read()) != null) {\n    if (seq.startsWith(\"\\u001b\")) {\n        if (seq.equals(\"\\u001b[A\")) {\n            System.out.println(\"Up arrow\");\n        } else { /* etc... */ }\n    } else if (seq.charAt(0) == 3) {\n        break; // Ctrl+C\n    } else {\n        System.out.println(\"Key pressed: \" + seq);\n    }\n}\n```\n\n### Handling mouse events\n\n```java\nterminal.enableRawMode();\nMouseTracking.enable(terminal, MouseTracking.Protocol.NORMAL);\nMouseTracking.enableEncoding(terminal, MouseTracking.Encoding.SGR);\nAnsiReader reader = new AnsiReader(() -\u003e terminal.read(-1));\nString seq;\nwhile ((seq = reader.read()) != null) {\n    if (MouseTracking.isMouseEvent(seq)) {\n        MouseEvent ev = MouseTracking.parse(seq);\n        System.out.printf(\"%-8s %-12s at (%d, %d)%n\",\n                ev.type(), ev.button(), ev.x(), ev.y());\n    }\n}\n```\n\n### Detecting terminal capabilities\n\n```java\nTermCaps caps = TermCaps.detect();\nif (caps.colors() \u003e= 256) {\n    // render with rich colours\n}\n```\n\n### Query colors\n\n```java\nColor bg = TermColors.queryBackground(terminal, () -\u003e terminal.read(500));\nif (bg != null) {\n    // luminance check for dark/light theme detection\n    boolean dark = (0.299 * bg.r8() + 0.587 * bg.g8() + 0.114 * bg.b8()) \u003c 128;\n}\n```\n\n## Modules\n\nThree artifacts are published independently:\n\n| Artifact | Description |\n|----------|-------------|\n| [`miniterm`](miniterm/README.md) | Legacy terminal implementation, Java 8+ |\n| [`miniterm-ffm`](miniterm-ffm/README.md) | Modern FFM-based terminal implementation, Java 22+ |\n| [`ansiparser`](ansiparser/README.md) | Compact ANSI escape sequence parser, Java 8+ |\n| [`mousetrack`](mousetrack/README.md) | Terminal mouse-tracking helpers and event parser, Java 8+ |\n| [`termcap`](termcap/README.md) | Terminal capability detection, Java 8+ |\n| [`colors`](colors/README.md) | Terminal colour palette querying and setting via OSC sequences, Java 8+ |\n\nFor dependency coordinates (Maven, Gradle, JBang) and module-specific usage details, see the individual module READMEs linked above.\n\n## Building\n\n```bash\n./mvnw clean install\n```\n\n## Running examples\n\nThe `examples/` folder contains several ready-to-run examples. Use the provided scripts to pick and run one interactively:\n\n**Linux/macOS:**\n\n```bash\n# Using the legacy (Java 8+) implementation\n./examples/run\n\n# Using the FFM (Java 22+) implementation\n./examples/run-ffm\n```\n\n**Windows:**\n\n```batch\n:: Using the legacy (Java 8+) implementation\nexamples\\run.bat\n\n:: Using the FFM (Java 22+) implementation\nexamples\\run-ffm.bat\n```\n\nThe scripts will list the available examples and let you choose one to run:\n\n- **FunShootingGallery** - simplistic game showing usage of the different APIs\n- **PrintAnsi** — prints the the ANSI sequence of each key pressed\n- **PrintCaps** — prints the capabilities that the terminal supports\n- **PrintColors** — detects and prints the colors that the terminal supports\n- **PrintKeys** — prints the code of each key pressed\n- **PrintMouse** — prints mouse events\n- **PrintSize** — prints the current terminal dimensions\n- **WatchSize** — watches and prints terminal size changes in real time\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodejive%2Fjava-miniterm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcodejive%2Fjava-miniterm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodejive%2Fjava-miniterm/lists"}