GitHub - J-StaR-Films-Studios/CreativeOS

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

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

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

Python 3.10+ — Download Python
pip — Comes with Python

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.

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'feat: add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
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

⬆ Back to Top

Built with 🔥 by Oluleke-Oke Goodness CEO J Star Films Studios

Name		Name	Last commit message	Last commit date
Latest commit History 65 Commits
00_System		00_System
.gitattributes		.gitattributes
.gitignore		.gitignore
.python-version		.python-version
ARCHITECTURE.md		ARCHITECTURE.md
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
README.md		README.md
SECURITY.md		SECURITY.md
USER MANUAL.md		USER MANUAL.md
desktop.ini		desktop.ini
install_cos.py		install_cos.py
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

What is CreativeOS?

📦 Installation

Prerequisites

Quick Install

Manual Configuration

Windows Integration

🚀 Quick Start

Create Your First Project

Adopt an Existing Folder

Sync Notes with Obsidian

📋 Command Hub

Creation

Maintenance

Workflow

Management

Help

🎨 Categories & Templates

Category Aliases

🧠 Architecture

Hub-and-Spoke Design

Project DNA (.project_meta.json)

The 3-Level Up Rule

🔧 Command Reference

cos new — Create Project

cos clone — Clone Repository

cos sync — Bidirectional Sync

cos travel — Archive Project

cos resurrect — Restore Project

🛡️ Security

📚 Documentation

🧪 Development

Setup Development Environment

Run Tests

Project Structure

🤝 Contributing

📄 License

🙏 Acknowledgments

About

Resources

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages