Skip to content

Repository files navigation

TechToolbox

The PowerShell Operator Framework for Modern Automation


TechToolbox unifies practical admin tooling into a single, predictable, portable module with shared configuration, logging, worker patterns, and a clean development model. It targets real-world enterprise operations: Active Directory lifecycle, Exchange Online / Purview workflows, remote diagnostics, browser cleanup, subnet tooling, and AI-assisted automation. The TechAgent runtime supports provider-based LLM routing (Ollama, OpenAI, OpenAI-compatible, Azure OpenAI) with quality controls and telemetry-backed reporting.


Contents

Quick Start

# Import the module (PowerShell 7+ recommended)Install-Module TechToolbox -Force
Import-Module TechToolbox -Force
# Browse all exported commandsGet-Command-Module TechToolbox |Sort-Object Name
# Get the built-in help catalogGet-ToolboxHelpGet-ToolboxHelp-List # Commands grouped by verbGet-ToolboxHelpInvoke-SubnetScan# Help for one command

One-Liner Demos

Disable-User-Identity 'jdoe'-Credential (Get-Credential)
Clear-BrowserProfileData-WhatIf
Get-SystemSnapshotInvoke-PurviewPurge-UserPrincipalName admin@company.com-CaseName Case-001-SearchName Custodian-01-WhatIf

Architecture Overview

TechToolbox follows a loader-driven, one-function-per-file pattern with deep internal helpers.

Module Layers

TechToolbox/
├── TechToolbox.psd1 # Module manifest (metadata + declared exports)
├── TechToolbox.psm1 # Bootstrap/loader (runtime path resolution, dot-sourcing, export wiring)
├── Public/ # Exported command scripts + export helper
│ ├── ActiveDirectory/ # AD lifecycle and identity operations
│ ├── AI/ # AI assistant and agent bridge commands
│ ├── Get/ # Read/query commands
│ ├── Invoke/ # Action/orchestration commands
│ ├── Set/ # Configuration/change commands
│ ├── Start_Stop/ # Session/service start-stop commands
│ ├── System/ # Local system and endpoint operations
│ ├── Test/ # Validation/diagnostic test commands
│ └── Export-ToolboxFunctions.ps1 # Canonical export discovery helper
├── Private/ # Internal helpers (dot-sourced, not exported)
│ ├── AADSync/ # AAD Connect internals
│ ├── ActiveDirectory/ # AD internal helper functions
│ ├── AI/ # Agent/prompt helper internals
│ ├── Browser/ # Browser cleanup internals
│ ├── Exchange/ # Exchange helper internals
│ ├── Input/ # Prompt/input utility internals
│ ├── Loader/ # Module home/bootstrap initialization
│ ├── Logging/ # Logging engine internals
│ ├── M365/ # Microsoft 365 helper internals
│ ├── Network/ # Network helper internals
│ ├── Purview/ # Purview/compliance helper internals
│ ├── Security/ # Security helper internals
│ └── System/ # Shared system helper internals
├── Workers/ # Remote / background task workers
├── Config/ # Runtime configuration (config.json, secrets)
│ ├── config.json # Base settings (git-tracked)
│ └── config.secrets.json # Tenant secrets (git-ignored)
├── src/
│ └── TechToolbox.Agent/ # Private C# agent source (git submodule)
│ ├── TechToolbox.Agent.csproj
│ └── Tests/ # xUnit tests for agent runtime
├── AgentRuntime/ # Packaged C# TechToolbox agent runtime for PSGallery installs
└── commands.md # Full command catalog with examples

How the Loader Works

  1. Manifest loads first -- TechToolbox.psd1 points to TechToolbox.psm1 and provides module metadata/declared exports.
  2. Bootstrap establishes module state -- TechToolbox.psm1 sets module/home paths and resolves runtime roots without first-import home copy.
  3. Private helpers are dot-sourced -- all .ps1 files under Private/ are loaded recursively into module scope.
  4. Public scripts are dot-sourced -- all .ps1 files under Public/ are loaded (excluding Export-ToolboxFunctions.ps1 in that pass).
  5. Exports are discovered and published -- at import time, Export-ToolboxFunctions discovers public function names, then Export-ModuleMember exports those functions.
  6. Runtime init remains lazy -- Initialize-TechToolboxRuntime initializes config/logging/interop/environment only when needed.

Path Tokens

Portable path tokens replace absolute paths for roaming safety:

TokenResolves ToUse For
%TT_ModuleRoot%C:\...\TechToolbox\Module-owned files (Config, Workers, Private)
%TT_Home%Module root by default (or override)Operational data root (logs, exports, prompt templates, history)
%TT_LogsRoot%Resolved logs rootLog file output paths
%TT_ExportsRoot%Resolved exports rootExported reports / files

TechAgent Architectural Principle

TechAgent follows an orchestrator-first design philosophy: the model proposes, the orchestrator decides.

LLM tool choices are treated as intent proposals, not direct execution commands. Before any tool runs, the orchestrator applies a standard control lifecycle:

  1. Eligibility and safety checks (execution mode, tool availability, destructive guardrails).
  2. Argument sufficiency and normalization (required args, coercion, prompt-derived hints).
  3. Uncertainty resolution (rewrite to discovery tools when arguments are incomplete).
  4. Evidence capture and loop control (result fingerprinting, repeated-call non-progress guards).
  5. Evidence-backed finalization (block placeholder final answers when concrete tool evidence exists).

This pattern is intentionally policy-driven so new tools can inherit stable behavior through declarative decision hooks and guard rules instead of one-off logic.

For any tool added or changed, keep regression coverage aligned to this philosophy:

  • Standard successful execution path.
  • Uncertainty rewrite and argument hydration path (when applicable).
  • Repeated-call non-progress guard behavior.
  • Final-answer evidence quality behavior.

Configuration

All configuration flows through Get-TechToolboxConfig. The effective config is the deep merge of:

  • Config/config.json -- base settings (tracked in source control)
  • Config/config.secrets.json -- tenant-specific and sensitive overrides (git-ignored)

Keep config.json limited to portable defaults, placeholders, and non-sensitive behavior settings. Put any environment-specific values there only if they are safe to share across every copy of the repo.

Move anything that identifies your environment into config.secrets.json, including:

  • Domain controllers and search bases
  • Tenant identifiers and org-specific UPN suffixes
  • Internal hostnames, servers, and UNC paths
  • Credential-related values or other machine-specific overrides

Environment Variables

VariablePurpose
TT_ConfigSecretsPathOverride the secrets file location
TT_DisableConfigSecretsMerge=1Skip merge for troubleshooting
TT_AGENT_LLM_API_KEYOptional runtime API key source for cloud providers
TT_AGENT_SEARCH_WEB_API_KEYOptional runtime API key source for SEARCH-WEB provider API

For cloud providers, Invoke-TechAgent also supports secure DPAPI-backed key storage in Config\config.secrets.json (settings.agent.apiKeyEncrypted) via Set-TechAgentApiKey. SEARCH-WEB uses the same pattern through settings.agent.searchWebApiKeyEncrypted via Set-TechAgentSearchWebApiKey.

Configuring Secrets

Use the ignored overlay for site-specific values. Start from Config/config.secrets.example.json, copy it to Config/config.secrets.json, then fill in your local values:

{
"settings": {
"tenant": {
"organizationName": "yourdomain.onmicrosoft.com",
"upnSuffix": "yourdomain.local",
"tenantId": "0000-0000-0000-0000"
},
"ad": {
"domainController": "DC01.yourdomain.local",
"searchBase": "DC=yourdomain,DC=local"
}
}
}

Baseline Settings (config.json)

{
"schemaVersion": 1,
"settings": {
"defaults": {
"promptForHostname": true,
"promptForCredentials": true,
"promptForDateRanges": true,
"showProgress": true,
"configPath": "%TT_ModuleRoot%\\Config\\config.json"
},
"logging": {
"enableConsole": true,
"enableFileLogging": true,
"minimumLevel": "Info",
"logPath": "%TT_LogsRoot%",
"logFileNameFormat": "TechToolbox_{yyyyMMdd}.log"
}
}
}

Invoke-TechAgent Prompt Example

Preferred prompt workflow

  • Invoke-TechAgent now defaults to AI\Tasks\CurrentTask.txt when no -Prompt or -PromptFile is supplied.
  • Use-TechAgentTaskTemplate can stage a reusable prompt template into that file before you run the agent.
  • -Prompt can still be used for inline prompt text, and -PromptFile can still target any other file when needed.
  • Provider routing supports ollama (default), openai, openai-compatible, and azure-openai.
  • Adaptive limit defaults now auto-select by provider: local-moderate for ollama and loopback openai-compatible, frontier-high for openai, azure-openai, and non-loopback openai-compatible endpoints.
  • Adaptive profile values are configurable in settings.agent.adaptiveLimitProfiles (enabled, modelMatchers, localModerate, frontierHigh, frontierXL) within Config\config.json.
  • Model matchers are evaluated first-match-wins and can route by wildcard or regex (pattern, profile, optional useRegex).
  • Each run now prints an adaptive preflight line with selected profile, matcher hit (if any), and resolved limit values.
  • Explicit environment variables always win over adaptive defaults: TT_AGENT_READ_FILE_SUMMARY_THRESHOLD_CHARS, TT_AGENT_MAX_TOOL_RESULT_CHARS, TT_AGENT_READ_FILE_PROMPT_COMPACT_THRESHOLD_CHARS, TT_AGENT_LLM_MAX_OUTPUT_TOKENS.
  • Set TT_AGENT_DISABLE_ADAPTIVE_LIMIT_OVERRIDES=true to disable adaptive limit injection entirely.
  • Quality controls support -Mode (execute, analyze, plan, chat), with chat as the default, -OutputContract (markdown, plain-text, json), -StrictPromptPreflight, and -QualityProfile.
  • Reasoning controls support -ReasoningEffort (low, medium, high, xhigh) and -ReasoningEffortAuto for automatic selection.
  • Authentication controls support -ToolCredential and -ToolCredentialVariableName (default: dac) for non-interactive tool authentication.
  • For tool auth, prefer Invoke-TechAgent parameters over embedding -Credential $dac inside prompt text.

Reasoning effort (GPT-5.3-Codex)

  • -ReasoningEffort sets an explicit override and takes precedence over auto mode.
  • -ReasoningEffortAuto enables policy-based effort selection when no explicit override is provided.
  • Auto policy uses prompt preflight telemetry and thinking mode to choose the effective effort.
    • Lower preflight scores and critical findings bias toward higher effort.
    • Higher preflight scores bias toward lower effort.
    • ThinkingMode off forces low; ThinkingMode on can raise low-effort auto outcomes.
  • Payload emission guardrails:
    • reasoning: { effort: "..." } is emitted only when provider is openai, model is gpt-5.3-codex, and effort is non-empty.
    • For unsupported provider/model combinations, the field is omitted and a diagnostic trace entry is written.

Example: provider and quality controls

# Cloud provider examplesInvoke-TechAgent-Prompt "Summarize these logs"-Provider openai -Model gpt-4o-mini
Invoke-TechAgent-Prompt "Plan migration steps"-Mode plan -Provider azure-openai -Endpoint https://your-resource.openai.azure.com-Deployment gpt-4o-mini
Invoke-TechAgent-Prompt "Help me decide what to do next"-Mode chat
# GPT-5.3-Codex reasoning effort examplesInvoke-TechAgent-Prompt "Analyze this incident timeline"-Provider openai -Model gpt-5.3-codex -ReasoningEffort high
Invoke-TechAgent-Prompt "Investigate this root cause"-Provider openai -Model gpt-5.3-codex -ReasoningEffortAuto -ThinkingMode on
# Quality guardrails and output contract examplesInvoke-TechAgent-Prompt "Investigate repeated login failures"-Mode analyze -OutputContract plain-text -StrictPromptPreflight
Invoke-TechAgent-Prompt "Return remediation checklist as JSON"-OutputContract json -QualityProfile balanced
# Quality telemetry summary for recent runsGet-TechAgentQualitySummary-Window 20Get-TechAgentQualitySummary-Window 30-IncludeRecent 10-AsJson
# Non-interactive credential context for tool calls$dac=Get-CredentialInvoke-TechAgent-Prompt "Disable only AD user jdoe. Use Disable-User with WhatIf and return markdown results."-Mode execute -ConfirmDestructive -ToolCredential $dac# Default variable lookup (ToolCredentialVariableName defaults to 'dac')$dac=Get-CredentialInvoke-TechAgent-Prompt "Disable only AD user jdoe. Use Disable-User with WhatIf and return markdown results."-Mode execute -ConfirmDestructive

Example: stage a task, then run it

Use-TechAgentTaskTemplate-Pick
Invoke-TechAgent

Example: Creating an Online Help Markdown File

The TechAgent uses a structured JSON decision schema and will have an easier time writing files when the prompt clearly specifies the required WRITE-FILE action. A new tool has been created for the agent to use when modifying existing files. REPLACE-IN-FILE should be preferred for localized edits.

Use a prompt similar to the following for consistent results:

Read this file:
C:\repos\TechToolbox\src\TechToolbox.Agent\Orchestrator\AgentOrchestrator.cs
Task: Add or improve XML documentation comments for every public type, public
constructor, and public method in this file.
Requirements:
- Modify the existing file in place at this exact path:
C:\repos\TechToolbox\src\TechToolbox.Agent\Orchestrator\AgentOrchestrator.cs
- Preserve all existing code and behavior.
- Only add or improve XML documentation comments.
- Prefer REPLACE-IN-FILE for localized edits to this existing file.
- Use WRITE-FILE only if a localized replacement is not practical.
- Do not stop after analysis.
- Do not summarize your plan before editing.
- Do not return a final answer until the file update has succeeded.

You can place that prompt directly into AI\Tasks\CurrentTask.txt, or use a template as a starting point:

Use-TechAgentTaskTemplate-List -Category CSharp
Use-TechAgentTaskTemplate-Template CSharp-XmlDocs-InPlace -Show
Use-TechAgentTaskTemplate-Template CSharp-XmlDocs-InPlace
Invoke-TechAgent

Command Reference

The full catalog is at COMMANDS.md. Below is a categorized summary organized by domain.

Active Directory & Identity Management

FunctionPurpose
Disable-UserDisables an AD user account (destructive)
Reset-ADPasswordResets an AD user password
New-OnPremUserFromTemplateCreates an on-prem user from a template
Search-UserSearches for AD users by criteria
Get-AllUsersEnumerates all AD users (with filters)
Get-LocalAdminMembersLists members of the local Administrators group
Initialize-TTWordListInitializes word list for Password generator

Exchange Online & Compliance

FunctionPurpose
Get-MessageTraceTraces an email message through Exchange / EOP
Invoke-PurviewPurgePurges content via Purview compliance portal (destructive)
Get-AuditSharedMailboxDeletionsAudits deleted shared mailboxes
Get-SharedMailboxPermissionsLists permissions on shared mailboxes
Get-AutodiscoverXmlInteractiveInteractive Autodiscover XML viewer
Set-EmailAliasSets or adds an email alias for a mailbox user
Set-ProxyAddressSets the proxy address (SMTP) for a mailbox user
Test-MailHeaderAuthTests email header authentication results

System Diagnostics & Health

FunctionPurpose
Get-SystemSnapshotCaptures key system state information
Get-ErrorEventsQueries Windows Event Logs for errors
Get-BatteryHealthReads battery health / cycle count from powercfg
Get-SystemUptimeReports system uptime
Get-WindowsProductKeyRetrieves the installed Windows product key
Get-PDQDiagLogsRetrieves PDQ diagnostics logs
Get-SystemTrustDiagnosticRuns a system trust diagnostic

Endpoint & Infrastructure Operations

FunctionPurpose
Invoke-SystemRepairRuns Windows system repair / SFC DISM operations
Reset-WindowsUpdateComponentsResets the Windows Update stack
Enable-NetFx3Enables the .NET Framework 3.5 feature
Set-PageFileSizeConfigures pagefile size (initial and maximum)
Set-OneTimeRebootSchedules a one-time reboot at a given time
Get-InstalledPrinters / Remove-PrintersManage installed printers (destructive on remove)

Remote Execution & Worker Patterns

FunctionPurpose
Invoke-AADSyncRemoteRuns an AAD Connect synchronization remotely
Start-NewPSRemoteSession / Stop-PSRemoteSessionManage PSRemoting sessions (destructive stop)
Get-RemoteInstalledSoftwareInventory software on remote computers
Copy-DirectoryCopies directory contents (robocopy wrapper)

Browser Cleanup

FunctionPurpose
Clear-BrowserProfileDataDeletes browser profile data (destructive)
Invoke-DownloadsCleanupCleans the Downloads folder (destructive)

Networking & Connectivity

FunctionPurpose
Invoke-SubnetScanScans a subnet for active hosts / services
Start-DnsQueryLoggerStarts DNS query logging for analysis
Watch-ISPConnectionMonitors ISP connection health over time

Credential Management

FunctionPurpose
Get-DomainAdminCredentialRetrieves domain admin credentials from secure store
Get-CUCredentialManagerContentsLists entries in the Credential Manager

AI-Assisted Workflows

FunctionPurpose
Invoke-TechAgentOrchestrates the agent-driven workflow engine with provider routing, execution modes, output contracts, and prompt preflight controls
Invoke-TechAgentGuiLaunches the packaged TechAgent desktop GUI from the gallery install or repo source tree
Use-TechAgentTaskTemplateStages reusable prompt templates to AI\Tasks\CurrentTask.txt for repeatable runs
Test-TechAgentProviderValidates provider configuration and optionally probes live connectivity/auth
Set-TechAgentApiKeySets/rotates/clears DPAPI-encrypted API keys used by cloud providers
Set-TechAgentSearchWebApiKeySets/rotates/clears DPAPI-encrypted SEARCH-WEB API keys used by the search tool
Get-TechAgentQualitySummarySummarizes recent run quality metrics from persisted memory history

Export & Packaging

FunctionPurpose
Export-ToolboxFunctionsExports all module functions as metadata for the agent
Get-ToolboxHelpDisplays the built-in help catalog
Get-TechToolboxConfigRetrieves or updates configuration

Common Workflows

Browser profile cleanup

Clear-BrowserProfileData-WhatIf # Dry runClear-BrowserProfileData-Browser Chrome # Target one browserClear-BrowserProfileData-Browser All -IncludeCache:$true# Full clean

Remote software inventory

Get-RemoteInstalledSoftware-ComputerName srv01,srv02 -Consolidated
Get-RemoteInstalledSoftware-ComputerName laptop01 -IncludeAppx -Credential (Get-Credential)

Purview purge flow

# Always preview firstInvoke-PurviewPurge-UserPrincipalName admin@company.com-CaseName Case-001-SearchName Search-001-WhatIf
# Execute when confirmedInvoke-PurviewPurge-UserPrincipalName admin@company.com-CaseName Case-001-SearchName Search-001

Exchange Online message trace

Get-MessageTrace-MessageId '<abc123@company.com>'Get-MessageTrace-MessageId '<abc123@company.com>'-StartDate (Get-Date).AddHours(-12) -EndDate (Get-Date)

AAD Connect remote sync

Invoke-AADSyncRemote-ComputerName 'aadconnect01'-PolicyType Delta
Invoke-AADSyncRemote-ComputerName 'aadconnect01'-PolicyType Initial -UseKerberos -WhatIf

Developer & Contributor Guide

Creating a New Command

  1. Create a new .ps1 file in Public/<Category>/<FunctionName>.ps1.
  2. Use the standard template (see below).
  3. Add the function name to FunctionsToExport in TechToolbox.psd1.
  4. Run Invoke-ScriptAnalyzer -Path .\TechToolbox -Recurse -Severity Error,Warning to validate.
  5. Test with -WhatIf and real data.
<#.SYNOPSIS Short description..DESCRIPTION Longer description explaining what the function does and when to use it..EXAMPLE New-MyCommand -Name 'test' Does something useful..PARAMETERName Description of the Name parameter..INPUTS None. You cannot pipe objects to this cmdlet..OUTPUTS System.String (or whatever is returned)..NOTES Requires: Admin rights, network access, etc.#>
[CmdletBinding(SupportsShouldProcess)]
param(
[Parameter(Mandatory=$true)]
[ValidateNotNullOrEmpty()]
[string]$Name
)
begin {}
process { Write-Host"$Name" }
end {}

Module Architecture Rules

  • One function per file -- every .ps1 in Public/ maps to one exported command.
  • Private helpers stay private -- nothing in Private/ is exported; use them only from other module functions.
  • No side effects on import -- the .psm1 bootstrap should not run user-facing code; lazy-init everything.
  • All paths use tokens -- never hardcode absolute paths; resolve via %TT_ModuleRoot% or %TT_Home%.
  • Module-root first import -- by default, first import does not stage/copy module content to a separate home path. Set TT_Home only when you intentionally want runtime data outside module root.
  • WhatIf support -- every destructive function must respect $PSCmdlet.ShouldProcess().

Testing Conventions

# Always run WhatIf before real executionClear-BrowserProfileData-WhatIf
Invoke-PurviewPurge-UserPrincipalName you@company.com-CaseName Case-001-SearchName Search-001-WhatIf
Get-RemoteInstalledSoftware-ComputerName srv01 -WhatIf
# ScriptAnalyzer on every PRInvoke-ScriptAnalyzer-Path .\TechToolbox -Recurse -Severity Error,Warning

Security Notes

  • Destructive actions -- functions marked destructive include Disable-User, Clear-BrowserProfileData, Invoke-PurviewPurge, Remove-EpicorEdgeAgent, Remove-Printers, Stop-PSRemoteSession, and others. Always use -WhatIf first.
  • Credentials -- sensitive credentials are stored in secure config files (git-ignored) or the Credential Manager. Never commit secrets.
  • CredSSP / Kerberos -- remote execution may require CredSSP delegation or Kerberos auth; configure remoting.credSSPDelegateComputers accordingly.

Troubleshooting

IssueResolution
Module import failsUse PowerShell 7+ and Import-Module .\TechToolbox.psd1 -Force
Command not foundCheck that it is listed in FunctionsToExport in the manifest
Config errorsVerify both config.json and config.secrets.json are valid JSON; use TT_DisableConfigSecretsMerge=1 to isolate issues
OpenAI/Azure OpenAI auth failsRun Test-TechAgentProvider -Provider <name> and set a key via Set-TechAgentApiKey or TT_AGENT_LLM_API_KEY
Path token resolution failsRun Test-TTPathRoots -EnsureDirectories to validate paths
Remoting failuresVerify WinRM is running, auth method matches server config, and credentials have appropriate privileges
Purview / EXO errorsConfirm required roles (Compliance Administrator, etc.) and Exchange Online module installed
Battery report failsRun elevated if powercfg is blocked by group policy
Logging silentEnsure log directories exist; check logging.enableFileLogging setting

Metadata

  • Author: Dan Damit
  • License: MIT License
  • Module version: 0.5.100
  • PowerShell requirement: 7+ (Core)
  • Repository:GitHub

v0.5.70 - "Provider Routing & Quality Controls"

Highlights

  • Provider-based LLM routing in TechAgent (ollama, openai, openai-compatible, azure-openai)
  • Cloud API key support with environment variable fallback and DPAPI-backed local secret storage
  • Prompt quality preflight scoring with strict-gate mode for higher-confidence runs
  • Execution mode contracts (execute, analyze, plan) and output contracts (markdown, plain-text, json)
  • Persisted run telemetry in agent memory plus quick quality rollups via Get-TechAgentQualitySummary

v0.5.0 - "AI & Metadata Milestone"

Highlights

  • AI-assisted workflow improvements (Export-ToolboxFunctions, Invoke-TechAgent enhancements)
  • Full help text capture in agent metadata export
  • Config system refinements and path token stabilization
  • Release Template

About

A PowerShell automation framework for IT Professionals' day-to-day ops.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages