Skip to content

Latest commit

 

History

History
156 lines (114 loc) · 4.14 KB

CLAUDE.md

File metadata and controls

156 lines (114 loc) · 4.14 KB

CLAUDE.md

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

Project Overview

tg-fuse is a FUSE-based virtual filesystem that enables sending files to Telegram contacts using standard Unix file operations. Users can cp files to virtual directories representing Telegram contacts (e.g., /mnt/tg/@username).

Build System

This project uses CMake with FetchContent for dependency management. Only system-level dependencies (FUSE libraries) need manual installation.

A Makefile is provided for convenience with common build targets.

Building the project

Using the Makefile (recommended):

make build-debug      # Build debug version in build/debug
make build-release    # Build release version in build/release
make clean-all        # Clean all build directories
make format           # Format all source files with clang-format

Using CMake directly:

mkdir build && cd build
cmake ..
make -j$(nproc)          # Linux
make -j$(sysctl -n hw.ncpu)  # macOS

Installing

cd build/release
sudo make install

Running the executable

# Configure API credentials (one-time, get from https://my.telegram.org/apps)
tg-fuse config set --api-id=YOUR_API_ID --api-hash=YOUR_API_HASH

# Authenticate
tg-fuse login

# Mount filesystem
tg-fuse mount /mnt/tg       # Linux
tg-fuse mount /Volumes/tg   # macOS

Dependencies

System dependencies (manual installation required)

  • Linux: libfuse3-dev, cmake, C++20 compiler
  • macOS: macFUSE, cmake, C++20 compiler (Xcode command line tools)

Third-party dependencies (automatically fetched via CMake FetchContent)

  • TDLib - Official Telegram client library
  • nlohmann/json - JSON parsing
  • spdlog - Logging framework
  • CLI11 - Command line argument parsing

Platform-Specific Considerations

Cross-platform FUSE support

The codebase uses conditional compilation for FUSE headers:

#ifdef __APPLE__
    #include <osxfuse/fuse.h>
#else
    #include <fuse3/fuse.h>
#endif

Mount points

  • Linux: /mnt/tg (default)
  • macOS: /Volumes/tg (default)

Architecture

Executables

The project builds two executables:

  • tg-fuse - CLI companion app with subcommands (mount, login, etc.)
  • tg-fused - FUSE daemon that runs the filesystem

Flow: tg-fuse mount /path → exec() into tg-fused → daemonise → FUSE loop

Directory Structure

/mount_point/
├── users/
│   └── <username>/
│       └── .info           # User information (read-only)
├── groups/
│   └── <groupname>/
│       └── .info           # Group information
├── channels/
│   └── <channelname>/
│       └── .info           # Channel information
├── @alice -> users/alice   # Symlinks for quick access
└── ...

Source Layout

  • src/ctl/ - CLI companion app
  • src/fused/ - FUSE daemon
  • src/fuse/ - FUSE library (operations, platform abstraction, VFS)
  • src/tg/ - Telegram wrapper library
  • include/fuse/ - FUSE library headers
  • include/tg/ - Telegram library headers

Platform Abstraction

Cross-platform FUSE support is abstracted behind C++ interfaces in include/fuse/platform.hpp:

  • FuseOperations - Abstract interface for filesystem operations
  • PlatformAdapter - Bridges platform-specific FUSE callbacks to the abstract interface

Uses C++20 features with TDLib's asynchronous API and C++ coroutines for handling Telegram operations.

Development Workflow

Since all dependencies are fetched automatically via CMake, the development process is:

  1. Clone repository
  2. Install only system FUSE libraries
  3. Run CMake (fetches all third-party dependencies)
  4. Build and develop

Running tests

# From debug build
cd build/debug && ctest

# From release build
cd build/release && ctest

Code formatting

IMPORTANT: Always run clang-format on modified files before committing.

# Format all source files (recommended)
make format

# Or format manually
clang-format -i src/main.cpp

The project uses a .clang-format configuration based on Google style with 120 column limit and 4-space indentation.