Building a GPT-Powered File Assistant That Won't Destroy Your System

Hook

What if your AI assistant could read your codebase, analyze images, and run shell commands—but you had to trust regex patterns to prevent it from wiping your hard drive?

Context

The promise of AI agents has always been tantalizing: natural language interfaces that translate intent into action. But when those actions involve filesystem operations and shell commands, the gap between "helpful assistant" and "catastrophic automation" gets uncomfortably narrow. GitHub is littered with LLM wrappers that expose dangerous capabilities with minimal safeguards, often treating security as an afterthought.

The avogabos/agents repository—specifically its Core Agent implementation—takes a pragmatic middle path. Rather than building yet another autonomous agent that tries to accomplish complex multi-step goals, it focuses on a narrower problem: giving GPT-4 supervised access to your local files through a conversational interface. It's designed for the developer who wants AI assistance navigating project directories, analyzing code, or performing batch file operations without leaving the terminal. The tool acknowledges that AI models will hallucinate, make mistakes, and occasionally suggest destructive actions—so it builds guard rails directly into the execution layer.

Technical Insight

At its core, the agent implements OpenAI's function calling pattern, but with several architectural decisions that set it apart from naive implementations. The system maintains a persistent message history that includes system prompts, user queries, assistant responses, and crucially, the results of function executions. When GPT-4 determines it needs to examine files, search directories, or run commands, it doesn't get raw access—instead, the agent executes the function within a sandboxed directory and feeds back a summarized result.

Here's how the token-aware summarization works:

def summarize_output(output: str, max_tokens: int = 1000) -> str:
    if len(output.split()) <= max_tokens:
        return output
    
    summary_client = OpenAI()
    response = summary_client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[
            {"role": "system", "content": "Summarize this output concisely."},
            {"role": "user", "content": output[:10000]}
        ],
        max_tokens=500
    )
    return response.choices[0].message.content

This dual-model approach is clever: the main reasoning loop uses GPT-4o for decision-making and natural language understanding, while a cheaper GPT-4o-mini instance handles the grunt work of compressing function outputs. When you ask the agent to "summarize all Python files in this project," it might invoke list_files, receive hundreds of lines of directory listings, compress that output to a few sentences, and only then feed it back into the main conversation. This prevents context window overflow and keeps costs manageable.

The safety mechanism relies on path validation and command filtering. Before executing any filesystem operation, the agent validates that the target path falls within a user-selected directory on the Desktop:

def validate_path(target_path: str, sandbox_root: str) -> bool:
    resolved_target = os.path.abspath(os.path.join(sandbox_root, target_path))
    resolved_sandbox = os.path.abspath(sandbox_root)
    return resolved_target.startswith(resolved_sandbox)

For shell commands, a blocklist approach prevents obviously dangerous operations:

DANGEROUS_PATTERNS = [
    r'rm\s+-rf',
    r'sudo',
    r'shutdown',
    r'reboot',
    r'mkfs',
    r'dd\s+if=',
    r'>\s*/dev/'
]

def is_safe_command(cmd: str) -> bool:
    for pattern in DANGEROUS_PATTERNS:
        if re.search(pattern, cmd, re.IGNORECASE):
            return False
    return True

The function calling loop maintains conversation continuity by appending function results as message objects with role "function". This allows GPT to reason about previous operations: "I tried to read config.json but it wasn't found, so let me search for configuration files instead." The agent also supports multi-modal capabilities—when you ask it to "analyze this diagram," it can encode images to base64 and send them to GPT-4's vision model.

Session persistence is handled through structured JSON logs. Each conversation gets saved with a GPT-generated title, raw message history, and metadata. This enables audit trails and the ability to resume or replay conversations:

session_data = {
    "title": generate_title(messages),
    "timestamp": datetime.now().isoformat(),
    "messages": messages,
    "target_directory": sandbox_root,
    "function_calls": function_call_count
}

The message pruning logic deserves attention because it directly impacts reliability. When the conversation history exceeds token limits, the agent removes the oldest function call results first, then older user/assistant exchanges, but always preserves the system prompt. This prioritization means recent context stays intact, but the agent might lose track of files it examined 20 turns ago—a trade-off between memory and context window economics.

Gotcha

The security model has significant blind spots. The regex-based command filtering can be bypassed through shell obfuscation—for example, r''m -rf (with quotes) might slip through a pattern looking for rm -rf as a contiguous string. Command injection through backticks, subshells, or environment variables could potentially circumvent the blocklist. The path validation is better but still assumes the sandbox root is correctly set and that symbolic links won't provide escape hatches. This is fundamentally a trust-based system: you're trusting GPT-4 not to get creative with command construction, and trusting your regex patterns to catch every dangerous variant. For personal projects and supervised use, this might be acceptable. For any production or shared environment, it's dangerously insufficient.

The Desktop-only restriction reveals platform assumptions baked into the design. The code constructs paths using os.path.join(os.path.expanduser('~/Desktop'), selected_dir), which works on macOS and most Linux desktop environments but breaks on headless servers or systems with different directory structures. Windows Desktop paths require special handling. Cross-platform reliability would require detecting the OS and adapting paths accordingly, or better yet, allowing arbitrary working directories with explicit user confirmation. The synchronous execution model also becomes painful with slow operations—running a recursive grep through a large codebase freezes the interface until completion, with no progress indication or ability to cancel.

Verdict

Use if: You want a conversational interface for supervised filesystem exploration within a controlled directory, you're comfortable reviewing suggested commands before they execute, you work primarily on a single platform (macOS or Linux desktop), and you value the simplicity of a standalone Python script over framework complexity. This shines for code reviews, data exploration in project directories, or batch file operations where GPT's reasoning helps navigate complexity. It's a personal productivity tool for developers who understand its limitations. Skip if: You need production-grade security (the safety mechanisms won't withstand adversarial prompts or sophisticated users), require cross-platform reliability, want streaming responses for long-running operations, need to work outside Desktop subdirectories, or expect the agent to maintain perfect context through very long conversations. The 8-star count suggests limited community vetting—you're adopting someone's experimental tool, not a battle-tested framework. For enterprise use or sensitive environments, look to more mature alternatives with formal security audits and active maintenance.