🐈 Neko Workspace

Neko turns your projects into reusable development workspaces that can be launched from anywhere.

Overview

Neko Workspace is a declarative development environment manager and a global workspace launcher. It automates the setup of everything a software project needs to run—editors, terminal sessions, browsers, layout windows, and automation hooks—so you can focus on coding.

The goal is simple:

Open your terminal, launch your workspace, and start coding immediately.

The Global Launcher

Gone are the days of manually navigating to project directories just to start working. Neko separates local discovery from global resolution:

1. Register your workspace once by running neko start inside your project directory.
2. Launch your workspace from anywhere using neko open <workspace-name>.

Programmable Desktop Composition

Neko restores your entire workspace visually. Configure window percentages, docking, and positions for your editor, terminals, and browser. Neko will snap them into place automatically.

editor:
  app: "code"
  layout:
    position: center
    width: 70
    height: 100

terminals:
  - name: "backend"
    shell: "pwsh"
    command: "pnpm dev"
    layout:
      dock: left
      width: 30
      height: 50

browser:
  urls:
    - "http://localhost:3000"
  layout:
    dock: right
    width: 30

---

Goals

• Global Accessibility: Launch projects from anywhere without switching directories.
• Reproducible Environments: Keep development tools and window layouts versioned.
• Automated Workflows: Spin up Docker, web servers, and browser tabs with one command.
• Beautiful DX: Enjoy a streamlined, automated developer experience.

---

Workspace Lifecycle

Neko supports a comprehensive CLI to manage your projects:

• neko start: Discovers the local neko.workspace.yaml, initializes the workspace, and registers it globally in the registry.
• neko open <workspace>: Looks up a registered workspace by name and launches it from anywhere on your system.
• neko status: Shows currently running, Neko-managed background processes.
• neko stop: Safely terminates tracked background processes without closing your interactive editor or browsers.
• neko restart: Restarts background services seamlessly.

---

Architecture

Neko Workspace is designed around a decoupled, declarative architecture.

Workspace Manifest
        ↓
Workspace Resolver
        ↓
Global Registry
        ↓
Workspace Launcher
        ↓
Applications & Layout Engine

1. Workspace Resolver: Locates your project either locally (current directory) or globally (via the registry).
2. Global Registry: A lightweight JSON database (~/.neko/registry.json) that maps your workspace names to their physical paths.
3. Workspace Launcher: The engine that parses your neko.workspace.yaml manifest and delegates tasks to specialized Executors.
4. Executors: Specialized modules (Browser, Editor, Terminal, Layout) that interact with the underlying OS to open apps and arrange windows.

---

Version Control

Neko Workspace acts as the definitive configuration of your development environment. Therefore, it is highly recommended to commit the neko.workspace.yaml manifest to your repository so other developers can instantly neko start the project.

Recommended .gitignore

# ==========================
# Neko Workspace
# ==========================

# Neko runtime state (PIDs, timestamps, process status)
.neko/

# Local developer overrides
neko.local.yaml
.neko.local/

---

Current Status

🚧 Under active development.

Global Launcher Complete — v0.6.0

Current capabilities:

✅ Global Workspace Registry (neko open) ✅ Advanced Native Layout Composition ✅ Manifest parsing & validation ✅ Terminal, Browser, and Editor execution ✅ Process tracking and lifecycle management (start, stop, restart) ✅ Hook automation (beforeStart, afterStart)

Next phase:

• Remote workspace synchronization
• Custom workspace templates
• Docker container orchestration

---

Roadmap

Architecture Phase

• Define workspace architecture.
• Define workspace domain.
• Define workspace schema.
• Implement Global Workspace Registry.

Implementation Phase

• Build execution engine & executors.
• Implement Workspace Launcher.
• Automate window layouts (Native Layout Engine).
• Build CLI (start, open, stop, restart).
• Implement neko list, neko rename, neko remove.
• Automate Docker project startup.

Release Phase

• Create installation scripts.
• Create workspace templates.
• Publish v1.0.

---

Why this project?

I realized that I wasn't losing time writing code. I was losing time before writing code.

Every day started with the same repetitive routine: opening editors, launching Docker, aligning multiple terminal windows, starting development servers, and opening browser tabs.

Neko Workspace exists to eliminate those repetitive steps. With neko open, your entire working context is just one command away.

---

License

MIT License.