CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

MiniOS is an educational operating system project supporting ARM64 and x86-64 architectures. The project follows a phased development approach with 7 main phases, currently at Phase 6 (75% complete) - Shell and User Interface. Phase 5 (File System) is complete with SFS achieving 100% feature parity with RAMFS. This is a learning OS designed to demonstrate core OS concepts clearly.

GitHub Project Management

Project Information

GitHub Project: #9 (https://github.com/users/ahmad-luqman/projects/9)
Repository: ahmad-luqman/build-your-own-os
Issue Tracking: All development tasks are tracked as GitHub issues with labels
Milestones: Phase-based milestones for tracking progress

Essential gh CLI Commands

View Project Status

# Quick dashboard view
./project_dashboard.sh

# Detailed status
./project_status.sh

# List all issues
gh issue list --repo ahmad-luqman/build-your-own-os

# List high priority issues
gh issue list --label "high-priority" --state open

# List bugs
gh issue list --label "bug" --state open

Working with Issues

# Create a new issue
gh issue create --title "Title" --body "Description" --label "bug,shell,high-priority"

# View an issue
gh issue view <number>

# Edit an issue (add labels)
gh issue edit <number> --add-label "in-progress"

# Assign issue to yourself
gh issue edit <number> --add-assignee @me

# Close an issue when complete
gh issue close <number> --comment "Fixed in commit <hash>"

# Reopen an issue
gh issue reopen <number>

Project Management

# Add issue to project
gh project item-add 9 --owner ahmad-luqman --url https://github.com/ahmad-luqman/build-your-own-os/issues/<number>

# View project
open https://github.com/users/ahmad-luqman/projects/9

Label System

Issues are organized with the following labels:

Priority Labels:

```
high-priority
```
- Critical issues needing immediate attention
```
medium-priority
```
- Important but not urgent
```
low-priority
```
- Nice to have improvements

Type Labels:

```
bug
```
- Something isn't working
```
feature
```
- New functionality
```
enhancement
```
- Improvements to existing features
```
documentation
```
- Documentation updates
```
testing
```
- Test-related tasks

Component Labels:

```
shell
```
- Shell/CLI related
```
sfs
```
- SFS filesystem
```
memory
```
- Memory management
```
performance
```
- Performance optimizations

Phase Labels:

```
phase-5
```
- File System
```
phase-6
```
- User Interface
```
phase-7
```
- Polish & Documentation

Current High Priority Issues

When starting work, check these first:

Bug Issues - Always fix bugs before adding features
High Priority Features - Critical functionality needed
Test Failures - Keep tests passing

Use:

gh issue list --label "bug" --state open

./project_dashboard.sh

Development Workflow

Starting Work on an Issue:

# Pick an issue
gh issue list --label "bug" --state open

# Assign to yourself
gh issue edit <number> --add-assignee @me

# Add in-progress label
gh issue edit <number> --add-label "in-progress"

# Create a branch (optional)
git checkout -b issue-<number>-description

During Development:

# Comment on progress
gh issue comment <number> --body "Working on fix, found that..."

# Link commits by mentioning issue
git commit -m "Fix: Description (#<number>)"

Completing an Issue:

# Close with comment
gh issue close <number> --comment "Fixed in commit <hash>"

# Or close via commit message
git commit -m "Fixes #<number>: Description"

Project Scripts

The following helper scripts are available:

./project_dashboard.sh
- Visual dashboard of project status
./project_status.sh
- Detailed status report
./setup_github_labels.sh
- Create/update labels (only run once)
./setup_github_project.sh
- Initial project setup (already complete)

Build Commands

Basic Build Operations

# Build for ARM64 (default)
make

# Build for x86-64
make ARCH=x86_64

# Clean build artifacts
make clean

# Build and test in VM
make test

# Build debug version with symbols and logging
make DEBUG=1

# Display build information
make info

# Quick build and test
make quick-test

Testing Commands

# Phase-specific testing
./tools/test-phase1.sh      # Phase 1 foundation testing
./tools/test-phase3.sh      # Phase 3 memory testing
./tools/test-phase4.sh      # Phase 4 system services testing

# Multi-phase testing
./test_phases.sh            # Test all completed phases
./test_all_phases.sh        # Comprehensive testing
./demo_phases_12.sh         # Demo phases 1-2

# Debug session
make debug                  # Start debug session

Architecture

Cross-Platform Support

Primary Target: ARM64 (AArch64) for UTM Virtual Machine on macOS
Secondary Target: x86-64 for broader compatibility via QEMU
Build System: Uses GNU Make with architecture-specific configuration files in
```
tools/build/arch-*.mk
```

Key Architectural Patterns

Hardware Abstraction Layer (HAL): Clean separation between architecture-specific and independent code
Microkernel-inspired design: Minimal kernel with modular components
Phase-based development: Each phase builds upon previous functionality

Source Code Structure

src/
├── arch/                 # Architecture-specific code (arm64/, x86_64/)
├── boot/                 # Bootloader implementations
├── kernel/               # Core kernel functionality
├── drivers/              # Device drivers (uart/, timer/, interrupt/)
├── fs/                   # File system implementations (vfs/, sfs/, block/, ramfs/)
├── shell/                # Shell implementation (core/, commands/, parser/, advanced/)
└── userland/             # User space applications and libraries

Current Implementation Status

Phase 6 In Progress (75% Complete) - Shell and User Interface

✅ Phase 1: Foundation Setup - Cross-platform build system
✅ Phase 2: Bootloader Implementation - UEFI (ARM64) and Multiboot2 (x86-64)
✅ Phase 3: Memory Management - MMU/Paging with virtual memory
✅ Phase 4: System Services - Device drivers, processes, interrupts, syscalls
✅ Phase 5: File System - VFS layer, SFS with 100% RAMFS feature parity, persistence
🔄 Phase 6: Shell (75%) - Interactive CLI, tab completion, pipes, I/O redirection, 25+ commands
⏳ Phase 7: Polish & Documentation

Recent Achievements (October 2025)

✅ Memory Management Audit (Issue #12) - Leak detection, cache management, meminfo command
✅ Pipe Execution (Issue #16) - Full pipe support with
```
|
```
operator
✅ Tab Completion (Issue #1) - Fixed cursor positioning bug
✅ SFS File Operations (Issues #4-#10, #15) - 100% feature parity with RAMFS
- File creation, read, write, delete, rename/move, copy
- Directory creation (nested), list, delete
- Data persistence across unmount/remount

Development Workflow

Cross-Compilation Setup

The build system automatically selects appropriate toolchains:

ARM64:

aarch64-elf-gcc

aarch64-elf-ld

aarch64-elf-as

x86-64:
```
x86_64-elf-gcc
```
,
```
x86_64-elf-ld
```
,
```
nasm
```

Build Process

Architecture detection and toolchain selection
Source file compilation with architecture-specific flags
Linking using architecture-specific linker scripts
Bootloader build and image creation
VM testing and debugging

Key Files to Understand

```
Makefile
```
: Main build configuration
```
src/kernel/kernel.h
```
: Core kernel structures and interfaces
```
src/include/
```
: Central header definitions
```
docs/ARCHITECTURE.md
```
: Detailed system architecture
```
docs/BUILD.md
```
: Build system documentation

Important Implementation Details

Memory Management

Virtual memory with 4KB pages
4-level page tables on both architectures
User/kernel space separation
ARM64: 256TB address spaces, x86-64: 128TB address spaces

System Call Interface

ARM64:
```
svc #0
```
instruction, arguments in x0-x5, return in x0
x86-64:
```
syscall
```
instruction, arguments in rdi, rsi, rdx, rcx, r8, r9, return in rax

File System

VFS abstraction layer supporting multiple file systems
SFS (Simple File System) implementation
Block device abstraction for storage
IMPORTANT: RAMFS is mounted at
```
/
```
(root), not
```
/ramfs
```

Process Management

Round-robin scheduling with priority levels
Preemptive multitasking via timer interrupts
Process structures with virtual memory spaces

Open Issues (Check GitHub for latest)

Current Open Issues

#14: Integration Tests (medium priority)
#13: SFS Unit Test Suite (medium priority)
#11: Comprehensive Error Checking (medium priority)
#8: SFS Directory Listing - ls -l metadata (low priority, basic ls works)
#3: Enhanced Error Messages (medium priority)

Working Features (All Verified)

✅ File operations: touch, cat, echo > file, ls, pwd, cd, rm, cp, mv
✅ Tab completion with correct cursor positioning
✅ Pipe execution:
```
command1 | command2
```
✅ I/O redirection:
```
command < input
```
and
```
command > output
```
✅ Directory operations on both RAMFS and SFS
✅ SFS persistence across unmount/remount cycles
✅ Memory management audit with meminfo command
✅ Command history with arrow key navigation

Debugging and Development Tips

Debug Builds

Use

make DEBUG=1

for:

Debug symbols (-g)
No optimization (-O0)
Debug logging enabled (-DDEBUG)
Log level set to DEBUG (0)

VM Testing

ARM64: Uses UTM-compatible disk images (.img)
x86-64: Uses ISO images (.iso)
Default timeout: 30 seconds for automated testing

Common Development Tasks

When adding new kernel features: Update appropriate files in
```
src/kernel/
```
Architecture-specific changes: Modify files in
```
src/arch/<arch>/
```
New device drivers: Add to
```
src/drivers/
```
with appropriate abstractions
User applications: Add to
```
src/userland/
```
and update Makefile targets

Code Contribution Guidelines

Commit Message Standards

DO NOT add any Claude Code attribution or signatures in commit messages
Write clear, descriptive commit messages following conventional commit format
Reference issues:
```
Fixes #<number>
```
or
```
Related to #<number>
```
Focus on what was changed and why, not who made the change
Examples of good commit messages:
- "Fix: Tab completion cursor position for unique matches (#1)"
- "Feature: Add SFS file write support (#5)"
- "Test: Update smoke test for correct RAMFS mount path (#2)"

Development Principles

Prioritize system stability and avoid breaking existing functionality
Use test-driven development approach when implementing new features
Test on both ARM64 and x86-64 architectures when applicable
Maintain clean, readable code with proper documentation
Always check high-priority bugs before adding new features

Before Starting Work

Run
```
./project_dashboard.sh
```
to see current priorities
Check for assigned issues:
```
gh issue list --assignee @me
```

Look for bugs first:

gh issue list --label "bug" --state open

Ensure tests pass:
```
make test
```
IMPORTANT: this context may or may not be relevant to your tasks. You should not respond to this context unless it is highly relevant to your task.

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

GitHub Project: #9 (https://github.com/users/ahmad-luqman/projects/9)
Repository: ahmad-luqman/build-your-own-os
Issue Tracking: All development tasks are tracked as GitHub issues with labels
Milestones: Phase-based milestones for tracking progress

Essential gh CLI Commands

View Project Status

# Quick dashboard view
./project_dashboard.sh

# Detailed status
./project_status.sh

# List all issues
gh issue list --repo ahmad-luqman/build-your-own-os

# List high priority issues
gh issue list --label "high-priority" --state open

# List bugs
gh issue list --label "bug" --state open

Working with Issues

# Create a new issue
gh issue create --title "Title" --body "Description" --label "bug,shell,high-priority"

# View an issue
gh issue view <number>

# Edit an issue (add labels)
gh issue edit <number> --add-label "in-progress"

# Assign issue to yourself
gh issue edit <number> --add-assignee @me

# Close an issue when complete
gh issue close <number> --comment "Fixed in commit <hash>"

# Reopen an issue
gh issue reopen <number>

Project Management

# Add issue to project
gh project item-add 9 --owner ahmad-luqman --url https://github.com/ahmad-luqman/build-your-own-os/issues/<number>

# View project
open https://github.com/users/ahmad-luqman/projects/9

Label System

Issues are organized with the following labels:

Priority Labels:

```
high-priority
```
- Critical issues needing immediate attention
```
medium-priority
```
- Important but not urgent
```
low-priority
```
- Nice to have improvements

Type Labels:

```
bug
```
- Something isn't working
```
feature
```
- New functionality
```
enhancement
```
- Improvements to existing features
```
documentation
```
- Documentation updates
```
testing
```
- Test-related tasks

Component Labels:

```
shell
```
- Shell/CLI related
```
sfs
```
- SFS filesystem
```
memory
```
- Memory management
```
performance
```
- Performance optimizations

Phase Labels:

```
phase-5
```
- File System
```
phase-6
```
- User Interface
```
phase-7
```
- Polish & Documentation

Current High Priority Issues

When starting work, check these first:

Bug Issues - Always fix bugs before adding features
High Priority Features - Critical functionality needed
Test Failures - Keep tests passing

Use:

gh issue list --label "bug" --state open

./project_dashboard.sh

Development Workflow

Starting Work on an Issue:

# Pick an issue
gh issue list --label "bug" --state open

# Assign to yourself
gh issue edit <number> --add-assignee @me

# Add in-progress label
gh issue edit <number> --add-label "in-progress"

# Create a branch (optional)
git checkout -b issue-<number>-description

During Development:

# Comment on progress
gh issue comment <number> --body "Working on fix, found that..."

# Link commits by mentioning issue
git commit -m "Fix: Description (#<number>)"

Completing an Issue:

# Close with comment
gh issue close <number> --comment "Fixed in commit <hash>"

# Or close via commit message
git commit -m "Fixes #<number>: Description"

Project Scripts

The following helper scripts are available:

./project_dashboard.sh
- Visual dashboard of project status
./project_status.sh
- Detailed status report
./setup_github_labels.sh
- Create/update labels (only run once)
./setup_github_project.sh
- Initial project setup (already complete)

Build Commands

Basic Build Operations

# Build for ARM64 (default)
make

# Build for x86-64
make ARCH=x86_64

# Clean build artifacts
make clean

# Build and test in VM
make test

# Build debug version with symbols and logging
make DEBUG=1

# Display build information
make info

# Quick build and test
make quick-test

Testing Commands

# Phase-specific testing
./tools/test-phase1.sh      # Phase 1 foundation testing
./tools/test-phase3.sh      # Phase 3 memory testing
./tools/test-phase4.sh      # Phase 4 system services testing

# Multi-phase testing
./test_phases.sh            # Test all completed phases
./test_all_phases.sh        # Comprehensive testing
./demo_phases_12.sh         # Demo phases 1-2

# Debug session
make debug                  # Start debug session

Architecture

Cross-Platform Support

Primary Target: ARM64 (AArch64) for UTM Virtual Machine on macOS
Secondary Target: x86-64 for broader compatibility via QEMU
Build System: Uses GNU Make with architecture-specific configuration files in
```
tools/build/arch-*.mk
```

Key Architectural Patterns

Hardware Abstraction Layer (HAL): Clean separation between architecture-specific and independent code
Microkernel-inspired design: Minimal kernel with modular components
Phase-based development: Each phase builds upon previous functionality

Source Code Structure

src/
├── arch/                 # Architecture-specific code (arm64/, x86_64/)
├── boot/                 # Bootloader implementations
├── kernel/               # Core kernel functionality
├── drivers/              # Device drivers (uart/, timer/, interrupt/)
├── fs/                   # File system implementations (vfs/, sfs/, block/, ramfs/)
├── shell/                # Shell implementation (core/, commands/, parser/, advanced/)
└── userland/             # User space applications and libraries

Current Implementation Status

Phase 6 In Progress (75% Complete) - Shell and User Interface

✅ Phase 1: Foundation Setup - Cross-platform build system
✅ Phase 2: Bootloader Implementation - UEFI (ARM64) and Multiboot2 (x86-64)
✅ Phase 3: Memory Management - MMU/Paging with virtual memory
✅ Phase 4: System Services - Device drivers, processes, interrupts, syscalls
✅ Phase 5: File System - VFS layer, SFS with 100% RAMFS feature parity, persistence
🔄 Phase 6: Shell (75%) - Interactive CLI, tab completion, pipes, I/O redirection, 25+ commands
⏳ Phase 7: Polish & Documentation

Recent Achievements (October 2025)

✅ Memory Management Audit (Issue #12) - Leak detection, cache management, meminfo command
✅ Pipe Execution (Issue #16) - Full pipe support with
```
|
```
operator
✅ Tab Completion (Issue #1) - Fixed cursor positioning bug
✅ SFS File Operations (Issues #4-#10, #15) - 100% feature parity with RAMFS
- File creation, read, write, delete, rename/move, copy
- Directory creation (nested), list, delete
- Data persistence across unmount/remount

Development Workflow

Cross-Compilation Setup

The build system automatically selects appropriate toolchains:

ARM64:

aarch64-elf-gcc

aarch64-elf-ld

aarch64-elf-as

x86-64:
```
x86_64-elf-gcc
```
,
```
x86_64-elf-ld
```
,
```
nasm
```

Build Process

Architecture detection and toolchain selection
Source file compilation with architecture-specific flags
Linking using architecture-specific linker scripts
Bootloader build and image creation
VM testing and debugging

Key Files to Understand

```
Makefile
```
: Main build configuration
```
src/kernel/kernel.h
```
: Core kernel structures and interfaces
```
src/include/
```
: Central header definitions
```
docs/ARCHITECTURE.md
```
: Detailed system architecture
```
docs/BUILD.md
```
: Build system documentation

Important Implementation Details

Memory Management

Virtual memory with 4KB pages
4-level page tables on both architectures
User/kernel space separation
ARM64: 256TB address spaces, x86-64: 128TB address spaces

System Call Interface

ARM64:
```
svc #0
```
instruction, arguments in x0-x5, return in x0
x86-64:
```
syscall
```
instruction, arguments in rdi, rsi, rdx, rcx, r8, r9, return in rax

File System

VFS abstraction layer supporting multiple file systems
SFS (Simple File System) implementation
Block device abstraction for storage
IMPORTANT: RAMFS is mounted at
```
/
```
(root), not
```
/ramfs
```

Process Management

Round-robin scheduling with priority levels
Preemptive multitasking via timer interrupts
Process structures with virtual memory spaces

Open Issues (Check GitHub for latest)

Current Open Issues

#14: Integration Tests (medium priority)
#13: SFS Unit Test Suite (medium priority)
#11: Comprehensive Error Checking (medium priority)
#8: SFS Directory Listing - ls -l metadata (low priority, basic ls works)
#3: Enhanced Error Messages (medium priority)

Working Features (All Verified)

✅ File operations: touch, cat, echo > file, ls, pwd, cd, rm, cp, mv
✅ Tab completion with correct cursor positioning
✅ Pipe execution:
```
command1 | command2
```
✅ I/O redirection:
```
command < input
```
and
```
command > output
```
✅ Directory operations on both RAMFS and SFS
✅ SFS persistence across unmount/remount cycles
✅ Memory management audit with meminfo command
✅ Command history with arrow key navigation

Debugging and Development Tips

Debug Builds

Use

make DEBUG=1

for:

Debug symbols (-g)
No optimization (-O0)
Debug logging enabled (-DDEBUG)
Log level set to DEBUG (0)

VM Testing

ARM64: Uses UTM-compatible disk images (.img)
x86-64: Uses ISO images (.iso)
Default timeout: 30 seconds for automated testing

Common Development Tasks

When adding new kernel features: Update appropriate files in
```
src/kernel/
```
Architecture-specific changes: Modify files in
```
src/arch/<arch>/
```
New device drivers: Add to
```
src/drivers/
```
with appropriate abstractions
User applications: Add to
```
src/userland/
```
and update Makefile targets

Code Contribution Guidelines

Commit Message Standards

DO NOT add any Claude Code attribution or signatures in commit messages
Write clear, descriptive commit messages following conventional commit format
Reference issues:
```
Fixes #<number>
```
or
```
Related to #<number>
```
Focus on what was changed and why, not who made the change
Examples of good commit messages:
- "Fix: Tab completion cursor position for unique matches (#1)"
- "Feature: Add SFS file write support (#5)"
- "Test: Update smoke test for correct RAMFS mount path (#2)"

Development Principles

Prioritize system stability and avoid breaking existing functionality
Use test-driven development approach when implementing new features
Test on both ARM64 and x86-64 architectures when applicable
Maintain clean, readable code with proper documentation
Always check high-priority bugs before adding new features

Before Starting Work

Run
```
./project_dashboard.sh
```
to see current priorities
Check for assigned issues:
```
gh issue list --assignee @me
```

Look for bugs first:

gh issue list --label "bug" --state open

Ensure tests pass:
```
make test
```
IMPORTANT: this context may or may not be relevant to your tasks. You should not respond to this context unless it is highly relevant to your task.

CLAUDE.md

Related Skills

Markdown Converter

Nano Banana Pro

1password