### Initialize Telecodex Configuration

Source: https://github.com/headcrab/telecodex/blob/master/README.md

Run this task to create the `telecodex.toml` configuration file from its example if it doesn't already exist.

```bash
task init-config
```

--------------------------------

### Run Telecodex Application

Source: https://github.com/headcrab/telecodex/blob/master/README.md

Execute this command to start the Telecodex application after completing the setup and configuration.

```bash
task run
```

--------------------------------

### Configuration: telecodex.toml Example

Source: https://context7.com/headcrab/telecodex/llms.txt

Minimal TOML configuration for Telecodex. Ensure all paths are absolute and the Telegram bot token is set in the specified environment variable.

```toml
// telecodex.toml (minimal working example)
// db_path = "telecodex.sqlite3"
// startup_admin_ids = [123456789]
// poll_timeout_seconds = 30
// edit_debounce_ms = 900
// max_text_chunk = 3500
// tmp_dir = "/home/user/telecodex/tmp"
//
// [telegram]
// bot_token_env = "TELEGRAM_BOT_TOKEN"
// api_base = "https://api.telegram.org"
// use_message_drafts = true
// primary_forum_chat_id = -1001234567890
// auto_create_topics = false
// forum_sync_topics_per_poll = 2
// stale_topic_days = 30
// stale_topic_action = "close"
//
// [codex]
// binary = "codex"
// default_cwd = "/home/user/projects/myproject"
// default_model = "gpt-4o"
// default_reasoning_effort = "medium"
// default_sandbox = "workspace-write"
// default_approval = "never"
// default_search_mode = "disabled"
// import_desktop_history = true
// import_cli_history = true
// seed_workspaces = ["/home/user/projects/myproject"]
// default_add_dirs = ["/home/user/projects/myproject"]
```

--------------------------------

### Transcribe Audio File with Handy Parakeet

Source: https://context7.com/headcrab/telecodex/llms.txt

Shows how to detect a local Handy Parakeet model, transcribe an audio file, and use the resulting text. Requires `ffmpeg` and the Parakeet model to be installed. Audio files are forwarded if no model is found.

```rust
use telecodex::transcribe::{detect_handy_parakeet_model_dir, transcribe_audio_file};
use std::path::PathBuf;

// Auto-detect Handy Parakeet model (checks APPDATA and LOCALAPPDATA on Windows)
// Model must contain: encoder-model.int8.onnx, decoder_joint-model.int8.onnx, nemo128.onnx, vocab.txt
if let Some(model_dir) = detect_handy_parakeet_model_dir() {
    let source = PathBuf::from("/tmp/voice_message.ogg");
    let scratch = PathBuf::from("/tmp/scratch");
    std::fs::create_dir_all(&scratch)?;

    let transcript = transcribe_audio_file(model_dir, source, scratch).await?;
    // transcript.engine == "Handy Parakeet"
    // transcript.text   == "Refactor the login module to use JWT."
    println!("Transcript: {}", transcript.text);
}

// Without a model, audio attachments are still forwarded to Codex
// as raw file paths (no transcript).

// ffmpeg conversion settings used internally:
// ffmpeg -y -i <source> -ac 1 -ar 16000 -c:a pcm_s16le <scratch/uuid.wav>
```

--------------------------------

### Initiate Codex Login from Telegram

Source: https://github.com/headcrab/telecodex/blob/master/README.md

After the bot starts, use this command in the Telegram chat with your bot to initiate the Codex login process.

```text
/login
```

--------------------------------

### Application Bootstrap with Rust

Source: https://context7.com/headcrab/telecodex/llms.txt

Initializes the Telecodex application, including Telegram connection, bot identity resolution, database opening, and optional audio transcription model detection. Returns an App handle ready for the main run loop.

```rust
use telecodex::app::App;
use telecodex::config::Config;
use std::path::PathBuf;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let config = Config::load(PathBuf::from("telecodex.toml"))?;
    let app = App::bootstrap(config).await?;
    // App::bootstrap performs:
    //   1. TelegramClient::new(token, api_base)
    //   2. telegram.get_me() to confirm token is valid
    //   3. detect_handy_parakeet_model_dir() for optional transcription
    //   4. Store::open(db_path, &admin_ids, &session_defaults)
    //   5. CodexRunner::new(codex_binary_path)
    app.run().await
}
```

--------------------------------

### Clone and Enter Telecodex Repository

Source: https://github.com/headcrab/telecodex/blob/master/README.md

Use these bash commands to clone the Telecodex repository and navigate into the project directory.

```bash
git clone https://github.com/Headcrab/telecodex.git
cd telecodex
```

--------------------------------

### Create and Manage Forum Topics

Source: https://context7.com/headcrab/telecodex/llms.txt

Use the `/topic` command to create new forum topics. Configuration options like `auto_create_topics` and `forum_sync_topics_per_poll` can control automatic topic creation during forum synchronization.

```text
# In any work topic:
/topic "My new feature"
# Creates a new forum topic named "My new feature" in primary_forum_chat_id,
# copies current session's cwd and runtime settings into it, and replies with the thread_id.

# Auto-creation (config):
# telegram.auto_create_topics = true   # creates topics automatically during forum sync
# telegram.forum_sync_topics_per_poll = 2   # throttle: max 2 topics created per poll cycle
# telegram.stale_topic_days = 30
# telegram.stale_topic_action = "close"   # or "delete"
```

--------------------------------

### Development Build and Run Tasks

Source: https://github.com/headcrab/telecodex/blob/master/README.md

Provides common development tasks for building, running, and testing the Telecodex project. Use these commands to manage the development lifecycle.

```bash
task build
task build-release
task run
task run-release
```

--------------------------------

### Open and Manage SQLite Session Store: `Store::open`

Source: https://context7.com/headcrab/telecodex/llms.txt

Opens or creates an SQLite database for storing session state, including current working directory, model, reasoning effort, and more. Initializes schema, seeds admin users, and logs startup events. Session state is keyed by `(chat_id, thread_id)`.

```rust
use telecodex::store::{Store, SessionDefaults};
use telecodex::models::{SessionKey, UserRole};
use telecodex::config::SearchMode;
use std::path::PathBuf;

let defaults = SessionDefaults {
    cwd: PathBuf::from("/home/user/project"),
    model: Some("gpt-4o".to_string()),
    reasoning_effort: Some("medium".to_string()),
    session_prompt: None,
    sandbox_mode: "workspace-write".to_string(),
    approval_policy: "never".to_string(),
    search_mode: SearchMode::Disabled,
    add_dirs: vec![],
};

let store = Store::open(
    std::path::Path::new("telecodex.sqlite3"),
    &[123456789_i64],   // startup_admin_ids -> seeded as UserRole::Admin
    &defaults,
)?;

// Ensure a session exists for a chat/topic (creates if absent)
let key = SessionKey::new(100200300_i64, Some(5_i64));  // chat_id=100200300, thread_id=5
let session = store.ensure_session(key, 123456789, &defaults)?;
println!("session id={} cwd={}", session.id, session.cwd.display());

// Update runtime settings
store.set_session_model(key, Some("o4-mini"))?;
store.set_session_reasoning_effort(key, Some("high"))?;
store.set_session_sandbox(key, "read-only")?;
store.set_session_search_mode(key, SearchMode::Live)?;
store.add_session_dir(key, std::path::Path::new("/home/user/shared"))?;

// Access control
store.upsert_user(987654321, UserRole::User, true)?;  // allow user
store.upsert_user(111111111, UserRole::User, false)?; // deny user
let user = store.get_user(987654321)?;

// Audit log
store.audit(Some(123456789), "manual_action", serde_json::json!({ "note": "test" }))?;

// Clear conversation (forces a fresh Codex thread on next turn)
store.clear_session_conversation(key)?;
```

--------------------------------

### Configure Runtime Session Settings

Source: https://context7.com/headcrab/telecodex/llms.txt

Per-session Codex runtime settings are persisted in SQLite. Commands like `/model`, `/think`, `/prompt`, `/sandbox`, `/approval`, `/search`, `/add-dir`, `/cd`, and `/pwd` allow fine-grained control over the session's behavior.

```text
# Model selection
/model gpt-4o           # set model
/model default          # revert to config default
/model                  # show current model + available models list (requires Codex login)

# Reasoning effort
/think high             # minimal | low | medium | high | default
/think default          # revert to config default

# Persistent session system prompt
/prompt You are a concise code reviewer. Focus on correctness.
/prompt clear           # remove session prompt

# Sandbox mode
/sandbox workspace-write         # default: can write inside cwd
/sandbox read-only               # read-only filesystem access
/sandbox danger-full-access      # unrestricted (use with caution)

# Approval policy
/approval never          # auto-approve all Codex actions
/approval on-request     # Codex asks for approval interactively
/approval untrusted      # strict mode

# Web search
/search on               # live web search
/search cached           # cached search results
/search off              # disabled (default)

# Extra writable directories
/add-dir /home/user/shared-assets
# Bot: "Writable dirs:\n- /home/user/project\n- /home/user/shared-assets"

# Working directory
/cd /home/user/other-project
/pwd
# Bot: "`/home/user/other-project`"

# Rate limits snapshot
/limits
# Shows latest Codex rate limit snapshot from local codex home directory
```

--------------------------------

### Loading Configuration with Rust

Source: https://context7.com/headcrab/telecodex/llms.txt

Loads and validates the Telecodex configuration from a TOML file. Ensures paths are absolute and resolves the codex binary. The Telegram bot token is read from an environment variable.

```rust
use telecodex::config::Config;
use std::path::PathBuf;

let config = Config::load(PathBuf::from("telecodex.toml"))?;
// config.telegram.resolve_token() -> reads TELEGRAM_BOT_TOKEN env var
// config.codex.binary -> resolved absolute path to codex binary
// config.codex.default_cwd -> canonicalized absolute path
```

--------------------------------

### Project Structure Overview

Source: https://github.com/headcrab/telecodex/blob/master/README.md

Illustrates the directory and file layout of the Telecodex project, highlighting the purpose of key modules within the src directory.

```text
src/
  app.rs            # main runtime loop and orchestration
  app/
    auth.rs         # Codex login/logout and device-code flow
    forum.rs        # forum/topic sync
    io.rs           # attachments and Telegram status delivery
    presentation.rs # formatting and keyboards
    support.rs      # shared helpers
    tests.rs        # app-level tests
    turns.rs        # turn execution pipeline
  commands.rs       # command parsing and help
  config.rs         # config loading and validation
  telegram.rs       # Telegram Bot API client
  store.rs          # SQLite persistence
  transcribe.rs     # optional audio transcription
```

--------------------------------

### List Importable Codex Environments

Source: https://context7.com/headcrab/telecodex/llms.txt

Command to list available Codex environments from various sources, enabling users to select one for creating a new Telegram forum topic. Requires `telegram.primary_forum_chat_id` to be configured.

```text
# Prerequisites:
# telegram.primary_forum_chat_id = -1001234567890  (a Telegram supergroup with Topics enabled)

# In the dashboard root topic:
/environments
```

--------------------------------

### Manage Session History with /history and /use

Source: https://context7.com/headcrab/telecodex/llms.txt

The `/history` command opens a paginated view of assistant messages. Use `/use` to bind the current session to a local Codex thread by ID or the latest thread for the current working directory.

```text
# Select the latest local Codex thread for the current cwd:
/use latest
# Bot replies: "Switched to Codex session `019ce672`."
# Followed by: last 6 history entries as a preview

# Select by prefix:
/use 019ce672
# -> finds thread whose UUID starts with "019ce672"

# Browse previous assistant messages:
/history
# Bot sends an inline-keyboard paginated view:
# Page 1/5 — "auth-refactor session"
# [← Prev]  [Next →]

# Keyboard callback data format:
# "his:<thread_id>:<page_index>"  -> render_history_page()
# History page cache: 64 entries, 5-minute TTL, LRU eviction
```

--------------------------------

### Running Telecodex with Cargo Tasks

Source: https://context7.com/headcrab/telecodex/llms.txt

Commands to build and run the Telecodex application using Cargo tasks. Allows specifying a custom configuration file path.

```bash
// Run with task runner:
// $ task run               # debug build
// $ task run-release       # release build
// $ task run CONFIG=telecodex.toml   # explicit config path
```

--------------------------------

### Enqueue Turn Request in Telecodex

Source: https://context7.com/headcrab/telecodex/llms.txt

Demonstrates how to enqueue a text-based turn request for processing by the Telecodex session worker. Ensure the `telecodex::models` are in scope.

```rust
use telecodex::models::{TurnRequest, SessionKey, LocalAttachment, AttachmentKind};

// Enqueue a text prompt turn
let request = TurnRequest {
    session_key: SessionKey::new(100200300, Some(5)),
    from_user_id: 123456789,
    prompt: "Refactor the login module to use JWT instead of sessions.".to_string(),
    runtime_instructions: None,
    attachments: vec![],
    review_mode: None,
    override_search_mode: None,
};
app.enqueue_turn(request, "private").await?;
```

--------------------------------

### Override Configuration Path

Source: https://github.com/headcrab/telecodex/blob/master/README.md

Demonstrates how to specify a custom configuration file path when running the Telecodex application. Useful for managing multiple configurations.

```bash
task run CONFIG=telecodex.toml
```

--------------------------------

### Telecodex Turn Pipeline Overview

Source: https://context7.com/headcrab/telecodex/llms.txt

Provides a conceptual overview of the steps involved in processing a turn within Telecodex, from workspace preparation to sending generated artifacts. This is an internal API flow.

```rust
// The turn pipeline:
// 1. prepare_turn_workspace() -> creates <cwd>/.telecodex/turns/<id>/out
// 2. enrich_audio_transcripts()  -> ffmpeg + Handy Parakeet if audio attachments
// 3. prepare_runtime_request()   -> builds final prompt with attachment paths and output dir instruction
// 4. enrich_runtime_request_with_codex_history() -> prepends last 8 history entries
// 5. CodexRunner::run_turn()     -> spawns `codex` process, streams CodexEvent via channel
// 6. LiveTurnSink::handle_event() -> edits Telegram placeholder with debounce (edit_debounce_ms)
// 7. send_generated_artifacts()  -> uploads files from out/ back to Telegram

// To stop a running turn:
// /stop  -> App::stop_session(key) -> CancellationToken::cancel()
```

--------------------------------

### Minimal Telecodex TOML Configuration

Source: https://github.com/headcrab/telecodex/blob/master/README.md

This TOML snippet shows essential configuration parameters for Telecodex, including database path, admin IDs, API settings, and Codex defaults.

```toml
db_path = "telecodex.sqlite3"
startup_admin_ids = [123456789]
poll_timeout_seconds = 30
edit_debounce_ms = 900
max_text_chunk = 3500
tmp_dir = "/absolute/path/to/telecodex/tmp"

[telegram]
bot_token_env = "TELEGRAM_BOT_TOKEN"
api_base = "https://api.telegram.org"
use_message_drafts = true

[codex]
binary = "codex"
default_cwd = "/absolute/path/to/telecodex"
default_model = "gpt-5.4"
default_reasoning_effort = "medium"
default_sandbox = "workspace-write"
default_approval = "never"
default_search_mode = "disabled"
import_desktop_history = true
import_cli_history = true
seed_workspaces = ["/absolute/path/to/workspace-a"]
default_add_dirs = ["/absolute/path/to/workspace"]
```

--------------------------------

### Set Telegram Bot Token Environment Variable

Source: https://github.com/headcrab/telecodex/blob/master/README.md

Before launching Telecodex, set the `TELEGRAM_BOT_TOKEN` environment variable with your bot's token.

```bash
export TELEGRAM_BOT_TOKEN="123456:replace-me"
```

--------------------------------

### Telecodex High-Level Workflow

Source: https://github.com/headcrab/telecodex/blob/master/README.md

Illustrates the data flow from Telegram through Telecodex to the local Codex CLI and back.

```text
Telegram chat/topic
        ↓
     Telecodex
        ↓
 local codex CLI
        ↓
  workspace files
        ↓
 Telegram edits + artifacts
```

--------------------------------

### Development Quality Assurance Tasks

Source: https://github.com/headcrab/telecodex/blob/master/README.md

Available tasks for maintaining code quality, including formatting and linting. Run these to keep the codebase clean and consistent.

```bash
task fmt
task fmt-check
task check
task clippy
```

--------------------------------

### Access Control Commands (Admin)

Source: https://context7.com/headcrab/telecodex/llms.txt

Admin-only commands manage the SQLite ACL. Use `/allow`, `/deny`, and `/role` to manage user access. All access control decisions are logged to `audit_log`.

```text
# Allow a new user (admin only):
/allow 987654321
# Bot: "User `987654321` allowed."

# Deny an existing user:
/deny 987654321
# Bot: "User `987654321` denied."

# Assign a role:
/role 987654321 admin
# Bot: "User `987654321` role set to `admin`."

# Unauthorized access:
# -> silently ignored; written to audit_log with action="access_denied"

# SQLite schema:
# users(tg_user_id INTEGER PRIMARY KEY, role TEXT, allowed INTEGER, created_at, updated_at)
# audit_log(id, actor_user_id, action TEXT, details_json TEXT, created_at TEXT)
```

--------------------------------

### Development Validation Tasks

Source: https://github.com/headcrab/telecodex/blob/master/README.md

Commands for validating the project's code quality and correctness during development. Ensure code adheres to standards.

```bash
task test
task verify
```

--------------------------------

### Telecodex Incoming File Paths

Source: https://github.com/headcrab/telecodex/blob/master/README.md

Specifies the directory where incoming files from Telegram are staged for processing by Telecodex.

```text
<session cwd>/.telecodex/inbox/...
```

--------------------------------

### Codex Device Login/Logout Flow in Telegram

Source: https://context7.com/headcrab/telecodex/llms.txt

Illustrates the user interaction and bot responses for initiating and completing a headless Codex device-code login flow, as well as logging out. Includes handling of rate limiting.

```text
# In Telegram chat with the bot:

/login
# Bot replies:
# Codex login started in headless device-code mode.
# 1. Open https://auth.openai.com/device
# 2. Sign in with your OpenAI account
# 3. Enter code `ABCD-1234`
# The code expires in about 15 minutes. I will post the result here when the login finishes.

# After successful authentication:
# Codex login completed.
# (auth detail from codex auth status)

/logout
# Bot replies:
# Codex credentials removed.

# If rate limited (429):
# Codex login is temporarily rate limited.
# Wait about 58s, then try /login again.
```

--------------------------------

### Telecodex Generated Deliverable Paths

Source: https://github.com/headcrab/telecodex/blob/master/README.md

Indicates the directory where files generated by Codex turns are placed before being sent back to Telegram.

```text
<session cwd>/.telecodex/turns/.../out
```

--------------------------------

### Telecodex Main Run Loop (Simplified)

Source: https://context7.com/headcrab/telecodex/llms.txt

The core long-polling loop for Telecodex. It handles Telegram updates, processes them, manages errors like conflicts, and respects retry delays. Graceful shutdown on Ctrl+C is also managed.

```rust
// Entry point in src/main.rs:
// App::bootstrap(config).await?.run().await
//
// Internal long-poll loop (simplified):
//
// loop {
//     tokio::select! {
//         _ = ctrl_c() => { notify_primary_user("stopped"); return Ok(()); }
//         result = telegram.get_updates(offset, poll_timeout_seconds) => {
//             match result {
//                 Ok(updates) => {
//                     for update in updates {
//                         store.save_last_update_id(update.update_id)?;
//                         app.process_update(update).await?;
//                     }
//                 }
//                 Err(e) if status == 409 CONFLICT => return Err("another instance running"),
//                 Err(e) => sleep(retry_after or 3s),
//             }
//         }
//     }
// }
```

--------------------------------

### Parse Telegram Message Text: `parse_command`

Source: https://context7.com/headcrab/telecodex/llms.txt

Parses raw Telegram message text into a `BridgeCommand` for local handling or a `Forward` value for external processing. Handles commands with bot username suffixes by normalizing them first. Unknown slash commands are always forwarded.

```rust
use telecodex::commands::{parse_command, ParsedInput, BridgeCommand};

// Bridge-handled command
let parsed = parse_command("/new", "my feature branch", "/new my feature branch")?;
assert!(matches!(parsed, ParsedInput::Bridge(BridgeCommand::New { title: Some(t) }) if t == "my feature branch"));

// Forwarded to Codex
let parsed = parse_command("/help", "", "/help")?;
assert!(matches!(parsed, ParsedInput::Forward(_)));

// Session runtime settings
let parsed = parse_command("/think", "high", "/think high")?;
assert!(matches!(parsed, ParsedInput::Bridge(BridgeCommand::Think { level: Some(l) }) if l == "high"));

// Review flow with flags
let parsed = parse_command("/review", "--base main look for regressions", "/review --base main look for regressions")?;
// -> BridgeCommand::Review(ReviewRequest { base: Some("main"), uncommitted: false, prompt: Some("look for regressions"), ... })

// Access control (admin only)
let parsed = parse_command("/role", "987654321 admin", "/role 987654321 admin")?;
// -> BridgeCommand::Role { user_id: 987654321, role: "admin" }
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.