All specs 137 total

src/cclaw/utils.py

Configures the application's logging system to write messages to both the console and a daily rotating file within the user's specified log directory. It accepts an optional string argument specifying the desired logging verbosity level, defaulting to "INFO". The function returns nothing and its primary side-effect is creating the necessary log directory structure and initializing the root logger with the specified handlers and format.

src/cclaw/utils.py

Converts a string containing Markdown formatting into a Telegram-compatible HTML string. It accepts one string input and returns a modified string output, handling conversions for bold text, italics, inline and fenced code blocks, and Markdown links. The function's notable side-effect is temporarily replacing links with unique placeholders to ensure correct HTML escaping and subsequent restoration as proper anchor tags.

src/cclaw/utils.py

Divides an input string into a list of smaller strings, ensuring each chunk respects a specified length limit, which defaults to a predefined constant. It accepts the message text as a string and an optional integer limit. The function returns a list of strings, where each element is a segment of the original message. It attempts to split the text at newline characters for cleaner segmentation and modifies the input text internally during processing.

src/cclaw/utils.py

Prompts the user for multiple lines of text, displaying a specific label to guide the input process. It accepts one string argument, which serves as the prompt label. The function reads input line by line until the user presses Enter on an empty line, and then returns all collected lines joined together into a single, stripped string.

src/cclaw/utils.py

Prompts the user for a single line of text input, displaying a customizable label before the prompt. It accepts a required label string and an optional default string value. If a default is provided, it displays the default value to the user and returns the user's input or the default if the input is empty. Otherwise, it simply prompts with the label and returns the user's input.

src/cclaw/token_compact.py

Writes successfully processed content back to their original file locations. It accepts a list of CompactResult objects, iterating through them to check for errors. If a result object indicates no error, its compacted content is written to the file path specified in its target. The function has no explicit return value but logs an informational message upon each successful write operation.

src/cclaw/token_compact.py

Generates a formatted, human-readable string report detailing token compaction results for a specified bot. It accepts the bot's name as a string and a list of CompactResult objects containing individual comparison data. The function outputs a single string summarizing the token savings for each result, categorizing them with appropriate emojis, and concludes with a total token savings summary.

src/cclaw/token_compact.py

Processes a list of content targets associated with a given bot name, using a specified language model to perform content compaction for each target sequentially. It accepts the bot's name as a required string and an optional model name, returning a list of CompactResult objects detailing the outcome for every processed target. The function handles individual failures gracefully, logging the error and recording it in the results without halting processing for subsequent targets.

src/cclaw/token_compact.py

Compresses the provided string content based on a specified document type by sending a formatted prompt to an external Claude AI model. It accepts the content, document type, a working directory, and optional model and timeout parameters. The function asynchronously executes the AI call and returns the resulting, stripped string output.

src/cclaw/token_compact.py

Collects a list of specific files from a given bot's directory structure, including MEMORY.md, user-defined SKILL.md files, and HEARTBEAT.md. It accepts the name of the bot as a string input and returns a list of CompactTarget objects, each containing file metadata like content and line counts. The function reads content from these files and populates the targets list, making no observable side-effects beyond returning the constructed list.

src/cclaw/skill.py

Gathers and merges environment variables from a list of provided skill names. It accepts a list of strings, where each string represents a skill name. The function returns a dictionary mapping environment variable names to their corresponding string values, accumulating settings from all successfully loaded skill configurations. No explicit side effects are noted beyond reading configuration data.

src/cclaw/skill.py

Gathers a consolidated list of tool patterns by iterating through a provided list of skill names. For each skill, it retrieves its configuration, extracts any specified allowed tools, and appends them to a running collection. The function returns a single, merged list containing all unique tool patterns found across all input skills. It has no observable side effects other than reading external skill configurations.

src/cclaw/skill.py

Installs a predefined skill template by copying all necessary files from the built-in package into the user's designated skills directory. It accepts a string representing the name of the desired built-in skill. The function returns the absolute path to the newly created and populated skill directory, and it raises errors if the skill name is invalid or if the skill is already present.

src/cclaw/skill.py

Combines the mcpServers dictionary from multiple skill configurations provided as a list of skill names. It iterates through each skill, loads its specific MCP configuration, and merges any found mcpServers into a single dictionary. If no skills yield an mcpServers section, the function returns None; otherwise, it returns a dictionary containing the consolidated mcpServers.

src/cclaw/skill.py

Retrieves the configuration settings for a given skill by reading a specific JSON file. It accepts a string representing the skill's name as input. The function returns a dictionary containing the loaded configuration if the file exists, or None otherwise. No external state is modified, only data is read from the filesystem.

src/cclaw/skill.py

Propagates the content of a specific CLAUDE.md file found within a given bot directory to all existing session subdirectories. It accepts a Path object pointing to the bot's root directory as input. The function returns nothing and has the side effect of overwriting or creating a CLAUDE.md file in every subdirectory within the specified sessions folder. If the source file or the sessions directory does not exist, the function exits silently.

src/cclaw/skill.py

Generates and overwrites a bot's CLAUDE.md file by reading the bot's configuration from a YAML file. It accepts a string representing the bot's name as input. The function produces no direct return value but modifies the file system by writing the newly composed Markdown content to the specified bot directory.

src/cclaw/skill.py

Composes a comprehensive Markdown string intended for a bot's profile document. It accepts the bot's name, personality text, role description, an optional list of active skill names, and an optional path to the bot's directory. The function constructs the document by assembling fixed sections for the name, personality, and role, and conditionally appends global memory content, a dedicated memory instruction section if a bot path is given, and detailed markdown for each specified skill. The output is a single, formatted string containing all assembled profile and skill information.

src/cclaw/skill.py

Retrieves a list of bot names that possess a specified skill. It accepts one string argument, the name of the skill to check for. The function reads the global configuration, iterates through all defined bots, and returns a list of strings containing the names of matching bots. No explicit side effects are noted beyond reading the application's configuration files.

src/cclaw/skill.py

Removes a specified skill from a bot's configuration by first loading the bot's existing settings using the bot's name and the skill's name as inputs. If the bot configuration is successfully loaded and the skill is present in the list of skills, the function updates the configuration by removing the skill and then saves the modified settings back to the system. The function returns nothing and its notable side-effect is modifying and persisting the bot's skill list in the configuration store.

src/cclaw/skill.py

Attaches a specified skill to an existing bot's configuration if it is not already present. It accepts the name of the target bot and the name of the skill to add as string inputs. The function returns nothing and its primary side-effect is updating and saving the bot's configuration file with the newly added skill.

src/cclaw/skill.py

Retrieves a list of skill names associated with a specified bot. It accepts one string argument representing the bot's name. The function returns a list of strings containing the skills, or an empty list if the bot configuration cannot be loaded or if no skills are defined. This process reads configuration data without modifying any external state.

src/cclaw/skill.py

Sets the operational status of a specified skill by first retrieving its current configuration using the provided skill name. If the skill configuration cannot be loaded, the function exits without making changes. Otherwise, it updates the skill's status within the configuration dictionary to "active" and then persists this modified configuration back to storage. The function returns nothing and its side-effect is updating the persistent state of the skill's configuration.

src/cclaw/skill.py

Determines if a specified software package meets its necessary operational prerequisites by checking for required system commands. It accepts a single string representing the package name and returns a list of strings detailing any missing commands or their suggested installation instructions. The function reads configuration details for the given name, and its primary side-effect is populating the returned list with error messages if dependencies are absent.

src/cclaw/skill.py

Deletes an entire skill directory and ensures it is detached from every bot currently utilizing it. It accepts a string representing the name of the skill to be removed. The function returns a boolean indicating whether the specified skill directory was successfully found and subsequently deleted. This process involves file system manipulation and interaction with bot management systems.

src/cclaw/skill.py

Constructs a dictionary representing a default skill configuration. It accepts a mandatory skill name, an optional description, and several optional parameters for skill type, required commands, and environment variables. The function initializes the configuration with the provided name and description, setting the status to "inactive," and conditionally adds type, required commands, or environment variables based on the inputs. It returns the fully assembled dictionary structure.

src/cclaw/skill.py

Creates a formatted string intended for a SKILL.md file. It accepts a required skill name and an optional descriptive text. The function outputs a markdown-formatted string containing the provided name as a main heading, the description, and a boilerplate "Instructions" section. No external side-effects occur.

src/cclaw/skill.py

Retrieves the designated skill type associated with a given skill name. It accepts one string argument representing the skill's name and returns either the skill's type as a string or None if the skill configuration cannot be loaded or if the type key is missing. This function does not modify any external state other than reading from the skill configuration source.

src/cclaw/skill.py

Determines the operational status of a specified skill name. It accepts one string argument representing the skill's name and returns a string indicating its status as "active", "inactive", or "not_found". The function first checks if the skill exists, then attempts to load its configuration; if no configuration file is found, it defaults to "active", otherwise, it returns the status specified in the configuration, defaulting to "inactive" if the status key is missing.

src/cclaw/skill.py

Retrieves the textual content of a skill's main markdown file. It accepts a string representing the skill's name as input. The function returns the file's content as a string if the file is found, or None if the specified skill directory does not contain the required SKILL.md file.

src/cclaw/skill.py

Retrieves the configuration settings for a specified skill by reading its associated YAML file. It accepts a string representing the skill's name as input. The function returns a dictionary containing the loaded configuration if the file exists, or None if the file is missing. If the YAML file is empty, it returns an empty dictionary instead of None.

src/cclaw/skill.py

Retrieves a list of dictionaries, where each dictionary represents a recognized skill found in a designated directory. It takes no inputs and returns a list containing structured information for every skill directory, including its name, type, status, description, and emoji. The function reads skill configuration files and attempts to populate the emoji field by first checking the local skill configuration and then falling back to a built-in template if necessary. No explicit side effects are noted beyond reading the file system to gather the skill metadata.

src/cclaw/session.py

Writes the provided string content to a designated global memory file. It requires one string argument representing the data to be saved. The function returns nothing and its primary side-effect is modifying the contents of the GLOBAL_MEMORY.md file in the user's home directory.

src/cclaw/session.py

Retrieves the textual content from a predefined global memory file. It accepts no arguments and returns the file's content as a string if the file exists and contains non-whitespace characters. If the file is missing or empty, the function returns None. This operation reads from the filesystem, which is the primary side-effect.

src/cclaw/session.py

Retrieves the textual content from a specified memory file associated with a given bot path. It accepts a Path object pointing to the bot's directory and returns the file's content as a string if the file exists and contains non-whitespace characters. If the file is missing or empty, the function returns None.

src/cclaw/session.py

Retrieves a list of all file paths contained within a specified session's workspace directory. It accepts a Path object representing the root of the session directory as input. The function returns a list of strings, where each string is the relative path to a file found inside the workspace. This process does not modify the filesystem but reads the directory structure.

src/cclaw/session.py

Appends a formatted conversation entry to a markdown file named according to the current UTC date within the specified session directory. It accepts a directory path, a role string ('user' or 'assistant'), and the message content as inputs. The function writes nothing to the console and returns no value. The primary side-effect is the modification of the designated conversation log file by appending the new entry.

src/cclaw/session.py

Reads the most recent conversation history by searching for dated markdown files within a specified directory, falling back to a legacy file if no dated files are found. It accepts a directory path and an optional maximum number of turns to retrieve. The function aggregates content from the found files, prepending older sections to maintain chronological order, and returns a single string containing the last specified number of conversation turns, or None if no content is available.

src/cclaw/session.py

Retrieves the stored session identifier for Claude by checking a specified directory for a configuration file. It accepts a Path object representing the directory where the ID is expected to reside. If the file exists, the function reads its content and returns the stripped string as the session ID; otherwise, it returns None. This function has no observable side effects other than reading the file system.

src/cclaw/session.py

Deletes all conversation files associated with a specific chat ID within a given bot's session directory. It accepts a path object pointing to the bot's location and an integer representing the chat identifier. The function returns nothing and its primary side-effect is the removal of all stored conversation data for that chat, while preserving the overall workspace directory structure.

src/cclaw/session.py

Generates a summary string detailing the total size and count of conversation files found within a specified directory path. It accepts a Path object representing the session directory and returns a formatted string summarizing the aggregated size in bytes and the number of files. The function reads all files matching a pattern within the directory, plus an optional legacy markdown file, accumulating their sizes and counts. If no relevant files are found, it returns the specific message "No conversation yet".

src/cclaw/session.py

Retrieves a list of file paths representing all conversation files within a specified directory. It accepts a Path object pointing to the session directory as input. The function returns a list of Path objects containing both pattern-matched and a specific legacy conversation file if present. No external state is modified, only a list of file paths is generated.

src/cclaw/session.py

Creates a necessary session directory structure based on a provided bot path and chat ID. It ensures the main session directory and a nested workspace subdirectory exist, copying a required CLAUDE.md file from the bot's location into the new session directory if it doesn't already exist. The function returns the absolute path to the newly established session directory.

src/cclaw/session.py

Scans a specified directory for subdirectories named like "chat_<id>" and extracts the integer ID from each one. It accepts a file path object pointing to the bot's root directory as input. The function returns a list of integers, where each integer represents a collected chat ID. This process reads the filesystem and has no other observable side effects.

src/cclaw/onboarding.py

Executes a comprehensive diagnostic routine to check the operational status of the environment and configuration. It takes no explicit inputs but relies on internal functions to load configuration files and validate external resources like Telegram tokens. The function prints various status messages to the console, indicating success, failure, or missing components, and has no return value.

src/cclaw/onboarding.py

Executes the complete initial setup process for the application. It first runs and displays necessary environment checks, exiting if any fail. Next, the function prompts the user for a Telegram token and bot profile details, finally calling a function to create the bot using the collected credentials. The function returns nothing and has the side effect of printing status messages to the console and potentially exiting the program.

src/cclaw/onboarding.py

Generates and persists a complete configuration for a new bot using a required token string, a dictionary containing bot metadata, and a dictionary holding profile details. It saves the resulting configuration to disk and updates the main bot configuration file. The function then prints a success message to the console detailing the bot's name, personality, role, and file path. Finally, it checks for and potentially restarts a background daemon process.

src/cclaw/onboarding.py

Stops and then restarts the cclaw daemon process to ensure any newly added bot configuration is recognized. It takes no inputs and returns nothing. The function prints status messages to the console, indicating the restart attempt and providing manual fallback instructions if an exception occurs during the process.

src/cclaw/onboarding.py

Gathers necessary configuration details for a bot by prompting the user for a name, personality description, and role description. It validates the provided name to ensure it consists only of ASCII letters, numbers, and hyphens, and checks that the name does not already exist. The function returns a dictionary containing the finalized, cleaned name and the multi-line text inputs for personality and description. No external state is modified besides printing messages to the console during the input process.

src/cclaw/onboarding.py

Prompts the user multiple times to input a Telegram bot token, displaying instructions on how to obtain it. It validates the provided token asynchronously against the Telegram API, printing success or failure messages to the console. Upon successful validation, it returns a tuple containing the valid token string and a dictionary of the bot's information. If all retry attempts fail, the function raises an exit signal.