🗒️ 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

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

📚 Documentation

🔒 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

🙏 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

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
codex-service		codex-service
logs		logs
scripts		scripts
stickys		stickys
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt
setup.py		setup.py

License

DeepBlueDynamics/Stickys

Folders and files

Latest commit

History

Repository files navigation