cat cyberdeck.txt

I've been working on a hobby project for several months and am at a point where procrastination is preventing meaningful progress, so I thought it would be a good time to document what I've done so far.

I'm building a cyberdeck.

Some would argue my current design doesn't meet the qualifications of a cyberdeck. I apply a much looser definition to the term. When I think cyberdeck I think retro-futurist, grimy, purpose-built and, in the context of much cyberpunk media, weapon. A cyberdeck isn't just a machine, it is a weapon and tool on the same level as a sword or a gun; a device that requires skill to properly wield. In the real world, I think a cyberdeck is an expression of one's hacker nature.

So far, my hacker nature involves spending too much money on hardware I have only a basic understanding of, and running low on motivation to physically build things. Hence the procrastination.

This project has been floating around in my head for years, fueled by the marvelous posts on r/cyberDeck. I initially was designing a wearable deck, inspired by the gargoyle rigs in Snow Crash: a sleeve-mounted Raspberry Pi with a fold-out keyboard and XR glasses for display. But I eventually became more interested in the function of the deck than the form: What was I going to actually use this thing for? The cyberpunk aesthetic is great, but I wanted a cyberpunk experience.

I became fixated on the idea of an embedded AI personality that lives in the device, and that evolved to a collection of hot-swappable AI companions that can assist the user in a netrunning RPG. This gamified interface will provide a deeper cyberpunk feel to the unit. As the software evolved, so did the way I wanted to interact with it. This build showed me a more achievable path forward, so I pivoted to a clamshell portable computer design.

First, I bought a case:

I also grabbed cables, screws, switches, and buttons to wire everything together.

Inputs would be a small mechanical keyboard and an SD card reader that functions to load the various "AI Cores" into the device.

Outputs would be a speaker (it talks!) and a collection of three displays: 1. An LCD panel for the TUI 2. A round LCD for the AI persona's "expressions" 3. A small e-ink display for system status

The "lore" of the device is that it's a stolen experimental field unit from Militech. It is designed to connect to networks and employ specialized AI actors to accomplish tasks and acquire data. It will run a sandboxed game simulation that allows the user to hack into virtual networks.

Though I have been slacking very hard on building the case and aesthetic components, I've been testing the integration of the software with the I/O devices and it's all working great!

Architecture at a glance

I've been writing this thing in Python and the codebase is a little over 12,000 lines at this point, spread across 60-something modules. That sounds like a lot for a hobby project, but I've been disciplined about keeping things organized into a layered architecture so I don't lose my mind:

1. Hardware layer: drivers and abstractions for the displays, the SD card reader, the speaker, and (eventually) the GPIO switches. This layer is allowed to fail gracefully if a piece of hardware isn't connected, which grants me freedom to test easily without needing to deploy to the actual device.
2. Manager layer: a collection of focused, single-purpose modules - MemoryManager, DisplayManager, ConversationManager, HandoffManager, etc. Each manager owns a specific subsystem and exposes a clean interface to the rest of the app.
3. Personality layer: the AI cores themselves, along with a host of persistent NPCs, defined as JSON configs. This is where the fiction lives.

The main CyberdeckTerminal class is essentially a delegation hub. It doesn't do much itself - it just owns the managers and wires them together:

class CyberdeckTerminal:
    def __init__(self):
        self.conversation_manager = ConversationManager()
        self.memory_manager = MemoryManager(self)
        self.handoff_manager = HandoffManager(self)
        self.tts_manager = TTSManager(self)
        self.display_manager = DisplayManager(self)
        self.command_handler = CommandHandler(self)
        self.core_authenticator = CoreAuthenticator(self)
        # ...and a bunch more

This pattern has paid off enormously. When I want to add a new feature, I usually know exactly which manager owns it. When something breaks, the blast radius is contained. And it makes the codebase navigable by future me (who has a terrible memory) and, eventually, others when I'm ready to make the code public.

A nice side effect of this layering is that physical events naturally cascade through all three layers. Insert a USB drive with a core config on it, and the hardware layer detects the mount, the manager layer loads and validates the config, and the personality layer swaps in a whole new system prompt and voice profile. Same flow for nearly every interaction in the system.

Hopefully this intro gives you a rough idea of what I'm building. In the next post, I'll go into detail about how the software works and how I've designed the AI personas. Later posts will cover the game and physical device design.