Skip to content

J-StaR-Films-Studios/CreativeOS

BranchesTags

Repository files navigation

   ██████╗██████╗ ███████╗ █████╗ ████████╗██╗██╗   ██╗███████╗ ██████╗ ███████╗
  ██╔════╝██╔══██╗██╔════╝██╔══██╗╚══██╔══╝██║██║   ██║██╔════╝██╔═══██╗██╔════╝
  ██║     ██████╔╝█████╗  ███████║   ██║   ██║██║   ██║█████╗  ██║   ██║███████╗
  ██║     ██╔══██╗██╔══╝  ██╔══██║   ██║   ██║╚██╗ ██╔╝██╔══╝  ██║   ██║╚════██║
  ╚██████╗██║  ██║███████╗██║  ██║   ██║   ██║ ╚████╔╝ ███████╗╚██████╔╝███████║
   ╚═════╝╚═╝  ╚═╝╚══════╝╚═╝  ╚═╝   ╚═╝   ╚═╝  ╚═══╝  ╚══════╝ ╚═════╝ ╚══════╝

Your Creative Nervous System — One CLI to Rule Your Entire Workflow

Version Python License Platform

Installation • Quick Start • Commands • Architecture • Docs

What is CreativeOS?

CreativeOS is a context-aware CLI that turns your file system into an intelligent, opinionated project management system. It bridges your active projects, Obsidian vault, archives, and portable drives through a single cos command.

Whether you're editing a YouTube video, writing code, producing a podcast, or designing for a client — CreativeOS gives every project the same structured foundation and keeps everything in sync.

Why creators love it:

  • 🎯 Instant Scaffolding — 12+ templates for Video, Code, AI, Audio, Design, Photo, Writing, Podcast, Course, and Client work
  • 🔄 Obsidian Sync — Bidirectional sync between project notes and your vault
  • 🧠 Context Awareness — Run commands from anywhere inside a project (3-Level Up Rule)
  • 📦 Archive & Resurrect — Move projects to cold storage. Bring them back when inspiration strikes
  • 🚀 Shuttle Drive — Pack a project onto an external drive and keep working anywhere
  • 🔒 Security Hardened — Input sanitization, path validation, and injection prevention baked in
  • ⚡ Beautiful CLI — Rich terminal output with panels, tables, and progress indicators

📦 Installation

Prerequisites

Quick Install

# Clone the repository
git clone https://github.com/JStaRFilms/CreativeOSFolder.git
cd CreativeOSFolder

# Install dependencies
pip install -r requirements.txt

# Run the setup wizard
python -m cos.cli setup

Manual Configuration

Copy the configuration template and customize paths:

cp 00_System/Config/config.template.json 00_System/Config/config.json

Edit config.json with your paths:

{
  "root_path": "C:\\CreativeOS",
  "projects_path": "C:\\CreativeOS\\01_Projects",
  "vault_path": "C:\\CreativeOS\\03_Vault",
  "archive_path": "D:\\OneDrive - MSFT\\Archive",
  "shuttle_path": "A:\\CreativeOS_Shuttle"
}

Windows Integration

Add cos.bat to your PATH for global access:

# The batch file uses relative paths automatically
# Just add 00_System\Scripts to your PATH environment variable

🚀 Quick Start

Create Your First Project

# Create a video project
cos new "My YouTube Video" -c Video

# Create a code project with Git
cos new "My App" -c Code -g

# Create a client project
cos new "Brand Refresh" -c Design --client "Acme Corp"

Adopt an Existing Folder

cd path/to/existing/project
cos init

Sync Notes with Obsidian

cos sync

📋 Command Hub

Creation

Command Description Example
new <name> Create a new project from template cos new "Video Project" -c Video
clone <url> Clone a Git repo and adopt it into COS cos clone https://github.com/user/repo.git
init Adopt current folder as a COS project cos init

Maintenance

Command Description Example
sync Sync project notes with Obsidian vault cos sync
thumbs Generate global thumbnail gallery cos thumbs
clean Sort and categorise Downloads folder cos clean
sort-exports File Exports/_Inbox into Year/Month cos sort-exports

Workflow

Command Description Example
export Open the project or month export folder cos export
travel Copy active project to shuttle drive cos travel
resurrect Restore an archived project to active cos resurrect "Old Project"

Management

Command Description Example
setup Configure CreativeOS (paths, categories, reset) cos setup
config View and edit configuration cos config show
category Manage project categories cos category list

Help

Command Description Example
help Show help for commands cos help new
--help Command-specific help cos new --help

Tip: Just type cos with no arguments to see the full Rich-formatted command hub in your terminal.

🎨 Categories & Templates

CreativeOS ships with 12+ project categories, each with an optimized folder structure:

Category Icon Template Description
Video 🎬 video_project YouTube, film, video production
Code 💻 plain_code Software development
Audio 🎵 audio_project Music and audio production
AI 🤖 ai_project Machine learning and AI projects
Design 🎨 design_project Graphic design and branding
Photo 📷 photo_project Photography projects
Writing ✍️ writing_project Articles, blogs, books
Podcast 🎙️ podcast_project Podcast production
Course 📚 course_project Online course creation
Client 👥 client_project Multi-discipline client work

Category Aliases

# These are equivalent
cos new "Project" -c Web    # → Code category
cos new "Project" -c ML     # → AI category
cos new "Project" -c Blog   # → Writing category

🧠 Architecture

Hub-and-Spoke Design

┌─────────────────────────────────────────────────────────────────┐
│                         CreativeOS                              │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐   │
│  │ Projects │◄──►│  Vault   │◄──►│ Archive  │◄──►│ Shuttle  │   │
│  │  (Hub)   │    │ (Notes)  │    │ (Cold)   │    │ (Mobile) │   │
│  └──────────┘    └──────────┘    └──────────┘    └──────────┘   │
│       │                                                         │
│       ▼                                                         │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │                    Templates                             │   │
│  │  Video │ Audio │ Design │ Photo │ Code │ Writing         │   │
│  └──────────────────────────────────────────────────────────┘   │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
  • Projects Path — Active workspace for current projects
  • Vault Path — Obsidian vault for notes and knowledge base
  • Archive Path — Cold storage for completed projects
  • Shuttle Path — External drive for portable work

Project DNA (.project_meta.json)

Every project carries a metadata file that defines its identity:

{
  "name": "My Video Project",
  "type": "Video",
  "created": "2026-02-25",
  "client": "Client Name",
  "git": "https://github.com/user/repo.git",
  "tags": ["youtube", "tutorial"],
  "status": "active"
}

The 3-Level Up Rule

Run commands from anywhere inside a project — CreativeOS walks up to find your project root:

C:\CreativeOS\01_Projects\Video\2026_Nike_Ad\04_Exports\Social_Media\Revisions\
         │
         │  cos export
         ▼
    Searches upward for .project_meta.json
    Found at: C:\CreativeOS\01_Projects\Video\2026_Nike_Ad\

🔧 Command Reference

cos new — Create Project

cos new <name> [options]

Arguments:
  name                    Project name (required)

Options:
  -c, --category CATEGORY Category: Video, Code, AI, Audio, Design, Photo, Writing, Podcast, Course, Client
                          Default: Video
  --client CLIENT         Associate with a client (creates client subfolder)
  -d, --date DATE         Backdate project (YYYY-MM-DD)
  -g, --git               Initialize Git repository
  -s, --simple            Use minimal folder structure

Examples:
  cos new "YouTube Tutorial" -c Video -g
  cos new "Mobile App" -c Code --client "Acme Corp" -g
  cos new "Podcast Episode 5" -c Podcast -d 2026-01-15

cos clone — Clone Repository

cos clone <url> [options]

Arguments:
  url                     Git repository URL (required)

Options:
  -n, --name NAME         Override folder name
  -c, --category CATEGORY Category (default: Code)
  --client CLIENT         Associate with a client

Examples:
  cos clone https://github.com/user/repo.git
  cos clone https://github.com/user/repo.git -n "My Project" -c AI

cos sync — Bidirectional Sync

cos sync

Synchronizes 00_Notes folders between projects and Obsidian vault:
  • New in Project → Push to Vault
  • New in Vault → Pull to Project
  • Conflict → Newer file wins (with backup)

cos travel — Archive Project

cos travel

Moves project to shuttle drive for portable work.
Creates _TRAVEL_LOG.txt with sync timestamp.

cos resurrect — Restore Project

cos resurrect <name>

Searches archive for project and restores to active projects.
Reads .project_meta.json to determine original location.

🛡️ Security

CreativeOS v2.1.0 includes comprehensive security hardening:

  • Input Sanitization — All user inputs are sanitized for safe path construction
  • Git URL Validation — Prevents flag injection in clone operations
  • PowerShell Sanitization — Escapes special characters in shell commands
  • Path Boundary Checks — Validates paths stay within trusted directories
  • Secure File Permissions — Restricts access to configuration files

See SECURITY.md for the full security policy.

📚 Documentation

Document Description
USER MANUAL.md Comprehensive command reference & advanced topics
ARCHITECTURE.md System architecture and design decisions
CHANGELOG.md Version history and changes
CONTRIBUTING.md Contribution guidelines
SECURITY.md Security policy

🧪 Development

Setup Development Environment

# Clone and install dev dependencies
git clone https://github.com/JStaRFilms/CreativeOSFolder.git
cd CreativeOSFolder
pip install -e ".[dev]"

Run Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=cos

# Type checking
mypy 00_System/Scripts/cos

# Linting
ruff check 00_System/Scripts/cos

Project Structure

CreativeOS/
├── 00_System/
│   ├── Config/
│   │   ├── config.json          # User configuration
│   │   ├── config.template.json # Configuration template
│   │   └── categories.json      # Category definitions
│   ├── Scripts/
│   │   ├── cos/                 # Main package
│   │   │   ├── cli.py           # CLI entry point
│   │   │   ├── config.py        # Configuration management
│   │   │   ├── security.py      # Input validation
│   │   │   ├── file_utils.py    # File operations
│   │   │   └── commands/        # Command implementations
│   │   └── tests/               # Test suite
│   └── Templates/               # Project templates
├── pyproject.toml               # Package metadata
├── requirements.txt             # Dependencies
└── README.md                    # You are here

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

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

📄 License

This project is licensed under the MIT License — see the LICENSE file for details.

🙏 Acknowledgments

  • Built with Rich for beautiful terminal output
  • Inspired by the need for a unified creative workflow system

About

No description, website, or topics provided.

Resources

Readme

Contributing

Contributing

Security policy

Security policy
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages