🗒️ Stickys — Advanced Desktop Sticky Notes with AI Integration

Stickys is a powerful desktop sticky notes application with integrated AI capabilities through OpenAI Codex and MCP (Model Context Protocol) tools. It provides a seamless experience for note-taking with voice transcription, agent automation, and Docker containerization support.

✨ Key Features

Core Functionality

• 📝 Desktop Sticky Notes: Borderless, always-on-top sticky notes with full drag & resize support
• 🎨 Customizable Colors: Multiple color themes for organizing your notes
• 💾 Auto-Save: Automatic saving of notes with version history
• 🔍 Smart Search: Fuzzy search across all active and saved notes
• 📸 Screenshot Capture: Take screenshots of individual notes or regions

AI & Voice Features

• 🎤 Voice Transcription: Real-time speech-to-text using Whisper model
• 🤖 AI Agent Integration: Automated note processing with OpenAI Codex
• 🔄 MCP Tool Support: Extensible tool system for AI agents
• 📊 Transcript Graph: Consensus-based text processing for accurate transcriptions

Developer Features

• 🐳 Docker Support: Full containerization with Codex CLI integration
• 🌐 TCP/HTTP API: Remote control via TCP socket (port 47821) and HTTP endpoints
• 🛠️ WSL & Docker Backends: Flexible execution environments
• 📦 Pip Installable: Standard Python package with dependencies

🚀 Quick Start

Prerequisites

• Python 3.9 or higher
• Windows 10/11 (primary platform)
• Docker (optional, for containerized Codex)
• Node.js 20+ (for Codex CLI)

Installation

Option 1: Local Development

# Clone the repository
git clone https://github.com/yourusername/gnosis-stickys.git
cd gnosis-stickys

# Install dependencies
pip install -r requirements.txt

# Run the application
python -m stickys

Option 2: Package Installation

# Install from the package directory
cd Stickys
pip install -e .

# Run the installed package
stickys

Option 3: Docker Container

# Build the Docker image
docker build -f Stickys/Dockerfile -t gnosis/stickys:dev .

# Set environment variable (PowerShell)
$env:STICKY_CODEX_BACKEND = 'docker'
$env:STICKY_CODEX_DOCKER_IMAGE = 'gnosis/stickys:dev'

# Run with Docker backend
python -m stickys

Quick Launch Script (PowerShell)

# Run with all features enabled
.\Stickys\scripts\run_stickys.ps1 -AutoBuild

📁 Project Structure

Stickys/
├── stickys/                    # Main Python package
│   ├── __main__.py            # Entry point
│   ├── sticky_notes.py        # Core application (252KB)
│   ├── tools/                 # Backend implementations
│   │   ├── docker_codex.py   # Docker Codex backend
│   │   ├── wsl_codex.py      # WSL Codex backend
│   │   └── tcp_test.py       # TCP connectivity testing
│   ├── mcp_tools/            # MCP tool integrations
│   └── logs/                 # Application logs
├── codex-service/            # HTTP service wrapper
│   ├── main.py              # FastAPI service
│   └── Dockerfile           # Service container
├── scripts/                  # Utility scripts
│   └── run_stickys.ps1      # PowerShell launcher
├── Dockerfile               # Main container image
├── pyproject.toml          # Package configuration
└── README.md               # This file

🔧 Configuration

Environment Variables

Core Settings

• STICKY_CODEX_BACKEND: Backend type (docker or wsl, default: wsl)
• STICKY_TCP_HOST: TCP server host (default: localhost)
• STICKY_TCP_PORT: TCP server port (default: 47821)

Voice Transcription

• STICKY_WHISPER_MODEL: Whisper model size (default: base.en)
• STICKY_WHISPER_COMPUTE: Compute type (default: int8)
• STICKY_ASR_WINDOW: Audio window in seconds (default: 15)
• STICKY_ASR_DEBOUNCE: Debounce time in seconds (default: 1.5)

Docker Configuration

• STICKY_CODEX_DOCKER_IMAGE: Docker image name (default: gnosis/stickys:dev)
• STICKY_CODEX_HOST_DIR: Host directory to mount
• STICKY_CODEX_CONTAINER_DIR: Container working directory (default: /workspace)

Agent Settings

• STICKY_AGENT_SETTLE_SECONDS: Agent idle time before processing (default: 20)
• STICKY_SEARCH_ASSIST: Enable search assistance (default: true)

🎮 Usage

Basic Operations

Creating Notes

• Launch the application to see the system tray icon
• Right-click tray icon → "New Sticky Note"
• Or use the keyboard shortcut: Win+Alt+S

Note Controls

• Drag: Click and hold the top bar to move notes
• Resize: Drag the corner handle (◢) to resize
• Copy: Click the copy button (📋) or Ctrl+Shift+C
• Screenshot: Click the camera button (📷)
• Close: Click the ⊗ button to save and hide

Voice Features

• Click the microphone button (🎤) to toggle transcription
• Visual meter shows audio levels
• Spinner indicates processing

AI Agent

• Click play button (▶) to enable agent
• Agent processes note content after idle period
• Pause button (⏸) to disable agent

TCP API Commands

Connect to port 47821 and send JSON commands:

import socket
import json
import struct

def send_command(cmd):
    sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
    sock.connect(('localhost', 47821))
    
    data = json.dumps(cmd).encode('utf-8')
    sock.send(struct.pack('!I', len(data)))
    sock.send(data)
    
    # Read response
    length = struct.unpack('!I', sock.recv(4))[0]
    response = json.loads(sock.recv(length).decode('utf-8'))
    
    sock.close()
    return response

# Example: Create a note
response = send_command({
    'type': 'create_note',
    'text': 'Hello from API!',
    'x': 100,
    'y': 100,
    'color': '#ffff99'
})

Available Commands

• create_note: Create new sticky note
• list_active: List all active notes
• list_saved: List saved notes
• search: Search notes by text
• read_note: Read note content
• update_note: Update note text/position
• delete_note: Delete a note
• agent_run: Trigger agent processing
• status: Get system status

MCP Tools Integration

Place custom MCP tools in the MCP/ directory at repo root:

# MCP/my_tool.py
def my_custom_tool(text: str) -> str:
    """Process text with custom logic"""
    return text.upper()

Tools are automatically available to the Codex agent.

🐳 Docker Deployment

Building the Image

# Build from repository root
docker build -f Stickys/Dockerfile -t gnosis/stickys:dev .

Running with Docker Backend

# Start the service container
docker run -d \
  --name codex-service \
  -p 8000:8000 \
  -p 1455:1455 \
  -v $(pwd):/workspace \
  gnosis/stickys:dev

# Configure environment
export STICKY_CODEX_BACKEND=docker
export STICKY_CODEX_HTTP_URL=http://localhost:8000

# Run the application
python -m stickys

Codex Service API

The Docker container exposes an HTTP API on port 8000:

• GET /status: Check service health
• POST /exec: Execute Codex commands
• POST /login: Initiate Codex authentication

🧪 Development

Running Tests

# Unit tests
pytest tests/

# Integration tests  
pytest tests/integration/

# TCP connectivity test
python -m stickys.tools.tcp_test

Code Style

# Format code
black stickys/

# Lint
pylint stickys/

# Type checking
mypy stickys/

Building Distribution

# Build wheel
cd Stickys
python -m build

# Install locally
pip install dist/Stickys-*.whl

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing)
5. Open a Pull Request

📚 Documentation

• API Reference
• MCP Tools Guide
• Docker Setup
• Configuration Guide

🔒 Security

• Authentication tokens stored in ~/.local/stickys/codex/
• TCP API bound to localhost only
• Docker containers run with limited privileges
• No external network access by default

📄 License

This project is proprietary software. All rights reserved.

🙏 Acknowledgments

• OpenAI for Codex CLI
• Anthropic for Claude integration
• Faster Whisper for voice transcription
• The Python community for excellent libraries

📞 Support

For issues and questions:

• GitHub Issues: Create an issue
• Email: dev@nuts.services

---

Made with ❤️ by the Gnosis team