Overview
A short tour of how Hunea thinks about design.
These choices may still change later, but they are relatively stable for now. Docs will follow if they shift.
If you mainly care about how to operate things, start with the Slash Menu.
- Why altscreen
- Mouse behavior varies by view
- The main view is one scrollable document
- Defaults stay restrained
Design philosophy
Core principle: tools exist to serve people, not the other way around.
Hunea was designed from the start to be a human-friendly product, and a lot of the design decisions flow from that intent.
Speaking as someone who is, arguably, in the industry: from my point of view, plenty of products are genuinely good, with solid design. It's just that they don't present themselves to users like me all that well — maybe the UI is awkward or unnatural, or the interaction is unintuitive and the cost of doing things is high.
There are many reasons for this. It's a bit like how few people want to write documentation: as long as a product works and ships without obvious problems, that's enough. Human-computer interaction design comes later. The priority is solving the problem — meeting the need.
On top of that, refining interaction and design takes a lot of thought and polish. That's completely understandable — I often feel the same way myself. Even building the TUI, or Nostra (Hunea's sister product), involves lots of pitfalls and details to get right. You spend ages on things that look trivial (like fixing the horizontal alignment between the macOS traffic lights and the controls on the right in Nostra), and usually nobody notices.
These "edge" things take 100 units of effort and don't necessarily return 50 — sometimes even less. You could spend that time shipping more features instead, making the product richer, solving more problems, or being more competitive.
But if we keep piling on features without attending to these foundational interactions and design decisions, can our apps still stay true to their original intent?
Maybe we started out building a food-delivery app, and then as the business grew and users multiplied, we bolted on feature after feature unrelated to food delivery — until you could watch videos, play games, or do some finance business in it.
That may not be a perfect analogy. The point is: do what your app is supposed to do, and do it well.
Back to human-computer interaction. We're in the AI era now, and a lot of tool usage has shifted from humans to AI. But in most cases, humans are still in charge. So I wanted to build a tool that is easy for humans to use.
And that it follows some ideas and design principles.
The following is taken from the Apple Developer website
I'm very grateful to Apple for these design principles — they guide and inspire me to try to design a good product
That said, I've only scratched the surface; there's still a lot for me to learn
Purpose
Make something meaningful.
Design starts with intention. Identify what matters most to the people you're designing for. Focus on making those things great, and you'll create an experience that people truly value.
Create value. The best designs reflect a constant orientation toward what makes a product genuinely useful. At every stage of development, ask what your product is for and whether the design serves that purpose.
Keep focused. Prioritize your app's most important features by aligning with how people want to use it, and focus on making those features truly great. A product with a clear use is more effective at helping people meet their goals.
Find new ways to solve the problem. Investigate existing solutions, and avoid re-creating them. Define what sets your product apart, and ask how your design can reflect that.
Hunea's design intent was, from the very beginning, to be an easy-to-use TUI tool for humans. It tries to solve a few foundational problems, roughly summarized as:
- "At-your-fingertips" transparency: you can inspect the assembled prompt, tools, and responses right inside Hunea — no packet capture or reading source code required.
- A simple, intuitive, easy-to-use interface.
- Decent speed and low resource usage (more optimization to come), aiming for cross-platform availability.
- Freedom and extensibility. Whether you're a first-time user or a power user, you can do what you want. Hunea will keep pushing in this direction.
- Other.
Hunea will keep being refined in future updates, with the focus on Hunea's core interaction and interface design.
Agency
Let people do things their own way.
An interface exists to help people accomplish their goals. Give them the freedom to act, keep them informed about what's happening, and make it easy to recover from mistakes.
Stay out of the way. People use your product to get things done. Often the best way to help them do this is to get them directly to the task or content at hand. The best designs are unobtrusive and present when people need them.
Give people the freedom to explore. Let them move through your interface and access features without being locked into specific flows or modes. When a guided flow is necessary, make it easy to skip or escape so people can get to the main experience quickly.
Help people recover from mistakes. When people know they can reverse an action or return to a previous state, they feel free to explore, and that freedom makes your interface more inviting. Build forgiveness into your design, and make it easy. Recovering from the unexpected shouldn't cost people their time or work.
Hunea's tree, resume, and resend features let users understand the current state from different angles, explore, and use the product.
Even if you make a mistake, it's fine — tree and friends are meant for going back in time. You don't need to worry about a misoperation causing unexpected problems.
More interaction improvements are coming; some critical paths for backtracking currently lack a second confirmation and clearer explanation. Hunea still has a long way to go here.
Responsibility
Act in people's best interest.
Your work has an impact on people's lives. Earn their trust by prioritizing safety and privacy, and being transparent about what your product does and why.
Be fully transparent about what your product does and why. You have an opportunity to build a relationship with someone from their very first interaction. Make sure your app's intentions are clear from the start. Provide a clear rationale when asking for permission, and when gathering data, be clear about what you collect and how you use it.
Keep people's information safe. People trust you to maintain the integrity of their data. Only collect what your product needs to function, and handle it with care. Anticipate ways it could be misused or cause harm, and put protections in place to prevent abuse and unintended consequences.
Hunea's code is fully open source, and every product update first ships a release on GitHub, then gets published to npm.
The whole process is completely transparent — no hidden black-box operations.
Hunea stores its config files and chat content in the specified local directories (unless your AI provider keeps data on their side — that's outside Hunea's control and can't be guaranteed). There's no telemetry (I wouldn't know how anyway...) and no data collection.
No sneaky data storage, and nothing weird produced behind your back.
Familiarity
Build on what people know.
Drawing on concepts people already understand helps them feel immediately at home. Ground your experience in established physical and digital patterns and apply them consistently throughout your design.
Use concepts that people know. People bring knowledge of the real world and other software to every new experience. Draw on both to make your interface feel familiar and intuitive.
Keep visuals and interactions consistent. Once you establish a behavior or appearance for an element, apply it throughout your design. Consistency helps people learn more quickly, and gives them confidence that new interactions will work the way they expect.
Provide clear feedback. Give people clear signals about what's happening as they use your app. Show when controls are available, indicate when content changes, and use system patterns to display alerts and offer choices. Consistent feedback helps keep people informed and in control.
Hunea's unbounded input box, mouse interaction, and keyboard-shortcut undo all come from experiences we're used to in everyday life. No extra mental burden is introduced.
And Hunea optionally lets you swap newline and send, so you can use Enter to insert a newline instead of sending the message — a consistent experience borrowed from note-taking apps (custom keybindings are planned for the future, to serve even more varied needs).
Space in Hunea means the spacebar. Unless stated otherwise, it always means "preview" in every other interface. You don't lose that consistent design just because you entered some other screen.
When something happens or a hint is needed, a clear toast pops up to tell you what matters, and system messages show the current state. It doesn't stay silent about everything.
Flexibility
Adapt to diverse contexts and needs.
People use your software in ways as unique as they are. The more your design acknowledges this, the more people feel welcome to use it. Be mindful of experiences other than yours, and try to support as many devices, types of interaction, and perspectives as possible.
Design for everyone. People are empowered by products designed with them in mind. Think about the diversity of people who may encounter your design, and take the range of their experiences, perspectives, and needs into account. Treat accessibility as a priority from the start. Design inclusively to reach the broadest possible audience and create a better experience for all.
Preserve a person's context. Help people feel at home as your design adapts across platforms and configurations. Keep content and controls in consistent, predictable positions, and use natural animations to ease transitions.
Consider a variety of input methods. People interact with their devices in different ways. Designing for as many inputs as possible — including voice, touch, keyboard, and more — means more people can use your product the way that works best for them.
Approach every platform with intention. Your software should feel polished and at home wherever it runs. Give each platform you support the same level of care.
Because Hunea tries to serve as many people as possible, beyond the already-settled core interaction and interface design, most other features are optional or customizable to a degree.
TUI doesn't lend itself well to accessibility work, but some attempts have been made — for example, using different colors while keeping them soft, large visual feedback to reflect interactions, using colors sparingly, and keeping the feedback design as consistent as possible.
Also, Hunea may consider voice-input support in the future. For now, pairing with a third-party app is recommended for a better experience. Since the sole developer and maintainer is me, some extensibility designs — even when planned — are still a long way from being implemented.
To me, Windows is just as important and high-priority as macOS and other platforms. No matter which OS you use, Hunea will try to deliver a consistent experience.
And again, because it's just me — stay tuned!
Simplicity
Be clear and direct.
A well-designed experience removes the unnecessary, with every element earning its place. When your interface is logically organized and straightforward to navigate, it's easier to get things done.
Include just what's necessary. Simplicity isn't minimalism. Aim for a focused, useful experience that keeps the important things close by and lets the others fall away.
Be concise. When you find the simplest way to say something, it's often the most universal, and the most helpful. Choose exactly the words you need to convey a concept or label a control.
Establish hierarchy. When form and function are readily apparent, people know how to reach a desired outcome. Prioritize recognizable controls and a consistent structure that helps people understand where they are and what comes next.
As mentioned earlier, Hunea tries to do its own job well and won't take on tasks or responsibilities that Hunea isn't meant to carry.
Hunea also strives to stay simple and minimize interface nesting. One screen does one thing well. It tries not to mix multiple concerns into a single screen.
Craft
Care about every detail.
Your design is a reflection of how much you care. It shows your dedication to delivering the best possible experience for people. Take the time to do the work well.
Quality sets the tone. Every element of your design shows people how much you care. Be deliberate with each decision, and strive for stunning visuals, smooth animations, precise wording, and thoughtful audio.
Experiment and iterate. Prototype early, try new approaches, and be willing to discard what doesn't work. Set a high bar for every feature, refine it, and try again. Test your product in real-world settings to make sure it's durable, reliable, and high-performing.
Maintain your craft. Shipping isn't the finish line. Keep your interface current with the latest platform capabilities and design patterns, and keep the quality bar high. Design is an ongoing commitment.
This one is very hard to achieve, but I'm trying to keep it up. As of August 6, 2026, Hunea has 400+ commits — a good share of them are work done purely to improve the experience.
Some commits are far apart in time, because sometimes multiple reviews and comparisons between approaches are needed.
Along the way, Hunea adopted external dependencies or designs like ACP, Rig, and GenAI.
But in later rounds of design, I vetoed and cleaned them all up one by one.
Still, I keep trying new approaches. For example, several recent updates introduced other dependencies or designs to improve Hunea's experience.
I hope Hunea can keep walking this path — maybe updating slowly, but staying stable and at a high standard. That might be easier for everyone to accept.
Delight
Make it human.
People remember how a product makes them feel. Think about the emotions that are right for your experience, and aim to deliver them in a way that's satisfying, enriching, and a joy to use.
Identify the emotion you want to inspire. Not all software feels the same to use. A fitness app might energize; a meditation app might calm; a game might thrill. Know the feeling you want to evoke, and let it shape your design.
Create defining moments. Every interaction is a chance to show what your software stands for. From a simple button press to an error message, consider whether each moment is an opportunity to add a touch of character that reflects the spirit of your design.
Don't mistake delight for decoration. Keep in mind that people are trying to accomplish a task, so don't let pursuit of delight for its own sake get in the way of your product's core purpose. Think about your overall aesthetic: Some designs benefit from a carefully considered practical touch, while others might prefer some whimsy. Experiment to find the right balance.
Consider the whole. Delight emerges as the sum of the consideration that you put into your product. It's the culmination of everything a person experiences as they use it: the freedom to act, the safety to explore, the comfort of familiar metaphors, and the flexibility to transition from one context to another. When you design with intent, focus, and care, the result is a product that people find naturally delightful.
This is a principle Hunea — and my other products, like Nostra — keep pursuing and maintaining.
Take Hunea: while a good part of its TUI design references Codex CLI, that doesn't mean Hunea wants to be a second Codex CLI.
Hunea incorporates a lot of my own thinking and design, plus many small details that may look minor but feel comfortable.
And then there's Hunea's documentation.
Even though a lot of it is generated with AI assistance, I review everything, keep it updated with every release, and clean up or optimize stale content.
I also personally spend a lot of time checking and writing documentation. This very article, for instance, was typed out character by character.
The upcoming "Slow Start" section will be written just as carefully and kept up to date — not a one-shot thing.
I hope Hunea can bring people delight, and that they can feel what makes Hunea unique and charming.
This kind of design and human consideration starts with Hunea, but doesn't end with Hunea.
Here's hoping things keep getting better.
In closing
The design principles above are what Apple's website carries today.
After writing that, I sighed, and then went back to look at the chapter titles of the 1992 edition of the Macintosh Human Interface Guidelines. It hit even deeper:
- Metaphors: With metaphors, you can use people's knowledge of the world around them to express the concepts and features of your app. Metaphors should be clear, concise, and have a real, familiar vehicle, so your users can seamlessly transfer that knowledge to the computer environment. For example, people often use folders to store their files. It's acceptable for people to store computer-created documents in computer-created folders, so they can organize their hard drive much like they organize their folders.
During development, Hunea absorbed the unified designs of similar apps and made some "compatibility" choices
For example, typing
/newmatches/clear, typing/quitmatches/exit, and so onI don't even remember when I switched from
cleartonewand fromquittoexit. Maybe the semantics are clearerBut I'm used to my old habits — especially
/quit, it's just too handy, hahaThese new commands still catch me out sometimes～
- Direct Manipulation: Direct manipulation lets people directly feel that they are operating on objects in the computer. According to the principle of direct manipulation, when users physically manipulate an object, the object must be visible on the screen. When the user acts on the object, the effect must be immediately visible to the user. For example, a user can move a file from one place to another by dragging an icon, or click directly in a text field to place the cursor where they want it.
No need to repeat this one
-
See-and-Point: On the desktop, users choose from the options shown on the screen to perform an action. Users click elements displayed on the desktop with a pointing device such as a mouse to interact with the screen directly — selecting objects or performing actions.
The Macintosh desktop works with two paradigms, but both share the same underlying assumptions: users can see what they're doing on the screen and can point at what they see with the mouse pointer. Both paradigms are based on a common user-action pattern: noun-then-verb.
In the first paradigm, users select the object (the noun) they want to operate on, then choose what to do with it (the verb)…
In the second paradigm, users drag an object (a noun) onto another object that represents an action (a verb)…
Many of Hunea's interfaces can be interacted with via mouse clicks or the scroll wheel
Interaction design will keep being filled in
I'm a bit tired writing this～
There's a lot of ideas and visions left for later. This was written on a whim, just to jot down some of my thoughts.
I'll be putting these ideas into the design of Hunea and other products going forward.
After all, people interact with products, not with my articles — haha!